{"record":{"id":"2d7a2444a1a948d0","repo":"gohugoio/hugo","slug":"failed-to-decode-segments-w","errorCode":null,"errorMessage":"failed to decode segments: %w","messagePattern":"failed to decode segments: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/segments/segments.go","lineNumber":318,"sourceCode":"\t\tvar segmentCfg map[string]SegmentConfig\n\t\tif err := mapstructure.WeakDecode(m, &segmentCfg); err != nil {\n\t\t\treturn nil, nil, err\n\t\t}\n\n\t\tsms := &Segments{\n\t\t\tbuilder: &segmentsBuilder{\n\t\t\t\tlogger:           logger,\n\t\t\t\tsegmentCfg:       segmentCfg,\n\t\t\t\tsegmentsToRender: segmentsToRender,\n\t\t\t},\n\t\t}\n\n\t\treturn sms, nil, nil\n\t}\n\n\tns, err := config.DecodeNamespace[map[string]SegmentConfig](in, buildConfig)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to decode segments: %w\", err)\n\t}\n\treturn ns, nil\n}\n","sourceCodeStart":300,"sourceCodeEnd":322,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/segments/segments.go#L300-L322","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped mapstructure error for the failing field and correct its type.","Follow the documented shape: each segment has `[[<name>.includes]]` / `[[<name>.excludes]]` arrays of matcher tables.","Validate TOML/YAML indentation — nested arrays of tables are easy to mis-indent."],"exampleFix":"# before\n[segments]\n  posts = \"posts/*\"\n\n# after\n[segments]\n  [segments.posts]\n    [[segments.posts.includes]]\n      path = [\"posts/*\"]","handlingStrategy":"validation","validationCode":"# Use hugo config to validate the segments namespace parses without decode errors.\nhugo config --kind segments >/dev/null || echo \"segments config invalid\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Follow the documented TOML structure: [segments.<name>] with [[<name>.includes]] arrays.","Validate TOML indentation after editing nested arrays of tables.","Run `hugo config` as a CI smoke test to surface decode errors early."],"tags":["segments","configuration","decoding","validation"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}