gohugoio/hugo · error

failed to decode segments: %w

Error message

failed to decode segments: %w

What it means

Hugo failed to decode the `segments` section of the site configuration into its internal SegmentConfig map. DecodeSegments wraps config.DecodeNamespace, which converts the raw config map (from hugo.toml/yaml/json) into typed segment definitions with excludes/includes matchers; any type mismatch or invalid glob inside a segment definition bubbles up here.

Source

Thrown at hugolib/segments/segments.go:318

		var segmentCfg map[string]SegmentConfig
		if err := mapstructure.WeakDecode(m, &segmentCfg); err != nil {
			return nil, nil, err
		}

		sms := &Segments{
			builder: &segmentsBuilder{
				logger:           logger,
				segmentCfg:       segmentCfg,
				segmentsToRender: segmentsToRender,
			},
		}

		return sms, nil, nil
	}

	ns, err := config.DecodeNamespace[map[string]SegmentConfig](in, buildConfig)
	if err != nil {
		return nil, fmt.Errorf("failed to decode segments: %w", err)
	}
	return ns, nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Validate the `segments` config block structure: each segment must be a table with `excludes`/`includes` arrays of matcher tables, e.g. `[[segments.docs.includes]] path = "/docs/**"`.
2. Read the wrapped error text — it names the offending field or glob; fix that matcher's type or pattern.
3. Compare against the official docs at gohugo.io/getting-started/configuration/#configure-segments.
4. Temporarily remove the segments block to confirm the rest of the config builds, then re-add matchers one at a time.

Example fix

# before (invalid: matcher is a plain string)
[segments.docs]
includes = "/docs/**"

# after
[[segments.docs.includes]]
path = "/docs/**"

// validate segments config before building
// hugo config | grep -A20 segments
var sc map[string]any
if err := mapstructure.WeakDecode(cfg.GetStringMap("segments"), &sc); err != nil {
    log.Fatalf("segments config invalid: %v", err)
}

if err := b.Build(); err != nil {
    if strings.Contains(err.Error(), "failed to decode segments") {
        // config shape error: check segments.<name>.includes/excludes entries
        return fmt.Errorf("fix segments in hugo config: %w", err)
    }
    return err
}

When it happens

Trigger: Building a site whose config contains a `[segments]` block that mapstructure.WeakDecode cannot map to map[string]SegmentConfig — e.g. a segment defined as a scalar or list instead of a table, wrong key names under excludes/includes, or an invalid glob pattern in a matcher (compiled via hglob.GetGlob, error 'failed to compile Glob').

Common situations: Introduced with Hugo's segmented rendering (v0.124+): users hand-writing `[segments.mysegment.includes]` blocks get the nesting wrong (matchers must be arrays of tables with kind/path/lang/output keys), or paste YAML examples into TOML with mismatched structure, or use invalid glob syntax in `path` matchers when setting up --renderSegments partial builds.

Related errors

• language %q not found
• unsupported format: %q
• failed to create workingDir: %w
• conf must be set
• errConfigNotSet

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/2d7a2444a1a948d0.json. Report an issue: GitHub ↗.