gohugoio/hugo · error

failed to decode segments

Error message

failed to decode segments: %w

What it means

Raised by DecodeSegments (segments.go:318) when config.DecodeNamespace fails while turning the raw `[segments]` map into SegmentConfig entries. The inner buildConfig uses mapstructure.WeakDecode into map[string]SegmentConfig, so structurally invalid segment definitions (wrong field types, non-map entries) bubble up wrapped here.

Solutions

1. Read the wrapped mapstructure error for the failing field and correct its type.
2. Follow the documented shape: each segment has `[[<name>.includes]]` / `[[<name>.excludes]]` arrays of matcher tables.
3. Validate TOML/YAML indentation — nested arrays of tables are easy to mis-indent.

Example fix

# before
[segments]
  posts = "posts/*"

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

# Use hugo config to validate the segments namespace parses without decode errors.
hugo config --kind segments >/dev/null || echo "segments config invalid"

When it happens

Trigger: A `[segments]` block where a segment value is not a map (e.g. a bare string); `includes`/`excludes` set to a single map instead of a list of maps; numeric values where strings/lists are expected; unknown top-level keys combined with strict decoding.

Common situations: First-time segments setup with mis-indented TOML or mistyped YAML; copying a segment example from docs of a different Hugo version whose schema changed; hand-editing hugo.toml and breaking the nested structure.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to compile Glob
• cardinalityThreshold threshold must be between 0 and 100
• markup must not be set, use mediaType
• permalink attribute not recognised
• permalinks configuration not supported for kind

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/2d7a2444a1a948d0. Report an issue: GitHub.

Appendix: 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 52c9bd7908)