{"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":"validation","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/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/segments/segments.go#L300-L322","documentation":"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.","triggerScenarios":"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').","commonSituations":"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.","solutions":["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/**\"`.","Read the wrapped error text — it names the offending field or glob; fix that matcher's type or pattern.","Compare against the official docs at gohugo.io/getting-started/configuration/#configure-segments.","Temporarily remove the segments block to confirm the rest of the config builds, then re-add matchers one at a time."],"exampleFix":"# before (invalid: matcher is a plain string)\n[segments.docs]\nincludes = \"/docs/**\"\n\n# after\n[[segments.docs.includes]]\npath = \"/docs/**\"","handlingStrategy":"validation","validationCode":"// validate segments config before building\n// hugo config | grep -A20 segments\nvar sc map[string]any\nif err := mapstructure.WeakDecode(cfg.GetStringMap(\"segments\"), &sc); err != nil {\n    log.Fatalf(\"segments config invalid: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := b.Build(); err != nil {\n    if strings.Contains(err.Error(), \"failed to decode segments\") {\n        // config shape error: check segments.<name>.includes/excludes entries\n        return fmt.Errorf(\"fix segments in hugo config: %w\", err)\n    }\n    return err\n}","preventionTips":["Validate segments config keys (includes/excludes with kind/path/lang/output matchers) against the documented schema before building","Run `hugo config` to confirm the parsed segments structure matches intent","Keep segment definitions minimal; add matchers incrementally and rebuild to isolate the bad entry"],"tags":["hugo","config","segments","mapstructure"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}