{"id":"3580bb4e31908e5c","repo":"gohugoio/hugo","slug":"failed-to-decode-languages-config-w","errorCode":null,"errorMessage":"failed to decode languages config: %w","messagePattern":"failed to decode languages config: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/allconfig/alldecoders.go","lineNumber":252,"sourceCode":"\t\t},\n\t},\n\t\"languages\": {\n\t\tkey: \"languages\",\n\t\tdecode: func(d decodeWeight, p decodeConfig) error {\n\t\t\tm := hmaps.CleanConfigStringMap(p.p.GetStringMap(d.key))\n\t\t\t// Root-level locale/languageCode is passed to DecodeConfig so it can\n\t\t\t// be applied to the default content language inside langs.DecodeConfig.\n\t\t\t// They are passed separately so that an explicit per-lang languageCode\n\t\t\t// can override a root-level languageCode (but not a root-level locale).\n\t\t\trootLocale := p.p.GetString(\"locale\")\n\t\t\trootLanguageCode := p.p.GetString(\"languagecode\")\n\t\t\tvar (\n\t\t\t\terr                    error\n\t\t\t\tdefaultContentLanguage string\n\t\t\t)\n\t\t\tp.c.Languages, defaultContentLanguage, err = langs.DecodeConfig(p.c.RootConfig.DefaultContentLanguage, rootLocale, rootLanguageCode, p.c.RootConfig.DisableLanguages, m)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to decode languages config: %w\", err)\n\t\t\t}\n\t\t\tfor k, v := range p.c.Languages.Config.LanguageConfigs {\n\t\t\t\tif v.Disabled {\n\t\t\t\t\tp.c.RootConfig.DisableLanguages = append(p.c.RootConfig.DisableLanguages, k)\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tp.c.RootConfig.DisableLanguages = hstrings.UniqueStringsReuse(p.c.RootConfig.DisableLanguages)\n\t\t\tsort.Strings(p.c.RootConfig.DisableLanguages)\n\t\t\tp.c.RootConfig.DefaultContentLanguage = defaultContentLanguage\n\t\t\treturn nil\n\t\t},\n\t},\n\t\"versions\": {\n\t\tkey: \"versions\",\n\t\tdecode: func(d decodeWeight, p decodeConfig) error {\n\t\t\tvar err error\n\t\t\tm := hmaps.CleanConfigStringMap(p.p.GetStringMap(d.key))","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/config/allconfig/alldecoders.go#L234-L270","documentation":"Emitted by the 'languages' entry of Hugo's config decoder table when langs.DecodeConfig cannot turn the [languages] config section into valid language definitions. It wraps the underlying validation error, e.g. an invalid defaultContentLanguage, a malformed language key, or inconsistent per-language settings, so the site build stops before an inconsistent multilingual setup is used.","triggerScenarios":"A [languages] map in hugo.toml/config.toml whose keys or values langs.DecodeConfig rejects: defaultContentLanguage set to a language not defined under [languages], invalid language keys (bad BCP-47-ish tags), non-map values under a language key, or conflicting root-level languageCode/locale versus per-language settings.","commonSituations":"Adding a second language to a previously monolingual site and forgetting to define the defaultContentLanguage under [languages]; typos like [languages.en] vs defaultContentLanguage = 'en-us'; YAML/TOML indentation errors that turn a language block into a scalar; upgrading Hugo versions where language config validation tightened.","solutions":["Ensure defaultContentLanguage matches one of the keys defined under [languages] exactly.","Check that every [languages.<key>] block is a table/map with valid fields (languageName, weight, contentDir, ...), not a scalar.","Read the wrapped inner error text — it names the specific offending key or value.","Validate the config file syntax (TOML/YAML) if the section parses into an unexpected shape."],"exampleFix":"# before\ndefaultContentLanguage = 'en-us'\n[languages.en]\nlanguageName = 'English'\n# after\ndefaultContentLanguage = 'en'\n[languages.en]\nlanguageName = 'English'","handlingStrategy":"validation","validationCode":"// Sanity-check the languages map shape before loading\nlangs, ok := cfg.Get(\"languages\").(map[string]any)\nif !ok {\n    return errors.New(\"languages must be a map of langCode -> settings\")\n}\nfor code, v := range langs {\n    if _, ok := v.(map[string]any); !ok {\n        return fmt.Errorf(\"languages.%s must be a table, got %T\", code, v)\n    }\n}","typeGuard":null,"tryCatchPattern":"conf, err := allconfig.LoadConfig(opts)\nif err != nil {\n    var fe herrors.FileError\n    if errors.As(err, &fe) {\n        // surface filename:line:col from the config file to the user\n    }\n    return err\n}","preventionTips":["Keep each [languages.xx] entry a table; a scalar value under languages fails decoding","Only use recognized per-language keys (languageName, weight, contentDir, title, params, etc.)","Validate hugo config renders after editing multilingual settings","Don't mix defaultContentLanguage values that have no matching languages entry"],"tags":["hugo","config","i18n","multilingual"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}