{"id":"16cc1c1adcec91ec","repo":"gohugoio/hugo","slug":"failed-to-decode-q-w","errorCode":null,"errorMessage":"failed to decode %q: %w","messagePattern":"failed to decode %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/allconfig/allconfig.go","lineNumber":1218,"sourceCode":"\t\t\t} else {\n\t\t\t\tlogger.Warnf(\"Skip unknown config key %q\", key)\n\t\t\t}\n\t\t}\n\t}\n\n\t// Sort them to get the dependency order right.\n\tsort.Slice(decoderSetups, func(i, j int) bool {\n\t\tki, kj := decoderSetups[i], decoderSetups[j]\n\t\tif ki.weight == kj.weight {\n\t\t\treturn ki.key < kj.key\n\t\t}\n\t\treturn ki.weight < kj.weight\n\t})\n\n\tfor _, v := range decoderSetups {\n\t\tp := decodeConfig{p: p, c: target, fs: fs, bcfg: bcfg, logger: logger}\n\t\tif err := v.decode(v, p); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to decode %q: %w\", v.key, err)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc createDefaultOutputFormats(allFormats output.Formats) map[string][]string {\n\tif len(allFormats) == 0 {\n\t\tpanic(\"no output formats\")\n\t}\n\trssOut, rssFound := allFormats.GetByName(output.RSSFormat.Name)\n\thtmlOut, _ := allFormats.GetByName(output.HTMLFormat.Name)\n\n\tdefaultListTypes := []string{htmlOut.Name}\n\tif rssFound {\n\t\tdefaultListTypes = append(defaultListTypes, rssOut.Name)\n\t}\n","sourceCodeStart":1200,"sourceCodeEnd":1236,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/config/allconfig/allconfig.go#L1200-L1236","documentation":"Raised in decodeConfigFromParams (allconfig.go:1218) when a single config section's decoder fails; v.key is the section name (e.g. \"markup\", \"outputs\", \"imaging\", \"languages\"). Hugo decodes the raw config map section-by-section via registered decodeWeight setups in dependency order, and wraps the first decoder failure with its section key so the user knows which top-level block is malformed.","triggerScenarios":"Any top-level config section whose structure fails mapstructure decoding or the section's own validation — e.g. invalid `imaging.quality` out of range, malformed `outputFormats`, invalid `permalinks` patterns, bad `security` policy values, or wrong types anywhere in a known section.","commonSituations":"Typos and wrong value types after hand-editing hugo.toml/yaml, upgrading Hugo across versions where a section's schema changed (e.g. markup, pagination), or merging theme example configs with incompatible structures.","solutions":["Identify the section from the quoted key in the message and inspect the wrapped inner error for the exact field.","Compare the section against the current Hugo docs schema for that key; fix types (map vs list vs scalar).","Bisect by commenting out the named section to confirm, then reintroduce fields incrementally.","If the error appeared after a Hugo upgrade, check the release notes for config schema changes in that section."],"exampleFix":"# before\n[imaging]\nquality = \"high\"\n# after\n[imaging]\nquality = 75","handlingStrategy":"validation","validationCode":"// The error names the config section that failed to decode.\n// Pre-check top-level sections are tables of the expected shape:\nknown := map[string]bool{\"params\": true, \"markup\": true, \"outputs\": true /* ... */}\nfor k, v := range rootCfg {\n    if known[k] {\n        if _, ok := v.(map[string]any); !ok && k != \"outputs\" {\n            return fmt.Errorf(\"%q must be a table, got %T\", k, v)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to decode\") {\n    // The %q in the message names the offending section (e.g. \"markup\", \"outputs\")\n    return fmt.Errorf(\"fix the named config section's structure/types, then reload: %w\", err)\n}","preventionTips":["Read the quoted section name in the error and check that exact block","Match the documented type for each section (table vs array vs scalar)","Validate with `hugo config` after every config edit","Avoid copying config snippets across Hugo versions without checking the current docs"],"tags":["hugo","config","decode","validation"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}