gohugoio/hugo · error

failed to decode config for language %q: %w

Error message

failed to decode config for language %q: %w

What it means

Wrapped error from fromLoadConfigResult (allconfig.go:1141) when decoding the merged per-language config clone fails. Hugo clones the base config for each language whose entry overrides root keys and re-runs decodeConfigFromParams on just those keys; any decoder error (bad type, invalid value) for that language's section is wrapped with the language key.

Source

Thrown at config/allconfig/allconfig.go:1141

						differentRootKeys = append(differentRootKeys, kk)
					default:
						// Apply new values to the root.
						differentRootKeys = append(differentRootKeys, "")
					}
				}
			}
			differentRootKeys = hstrings.UniqueStringsSorted(differentRootKeys)

			if len(differentRootKeys) == 0 {
				langConfigMap[k] = all
				continue
			}

			// Create a copy of the complete config and replace the root keys with the language specific ones.
			clone := all.cloneForLang()

			if err := decodeConfigFromParams(fs, logger, bcfg, mergedConfig, clone, differentRootKeys); err != nil {
				return nil, fmt.Errorf("failed to decode config for language %q: %w", k, err)
			}
			if err := clone.CompileConfig(logger); err != nil {
				return nil, err
			}

			// Adjust Goldmark config defaults for multilingual, single-host sites.
			if len(languagesConfig) > 1 && !isMultihost && !clone.Markup.Goldmark.DuplicateResourceFiles {
				if clone.Markup.Goldmark.RenderHooks.Image.UseEmbedded == gc.RenderHookUseEmbeddedAuto {
					clone.Markup.Goldmark.RenderHooks.Image.UseEmbedded = gc.RenderHookUseEmbeddedFallback
				}
				if clone.Markup.Goldmark.RenderHooks.Link.UseEmbedded == gc.RenderHookUseEmbeddedAuto {
					clone.Markup.Goldmark.RenderHooks.Link.UseEmbedded = gc.RenderHookUseEmbeddedFallback
				}
			}

			langConfigMap[k] = clone
		case hmaps.ParamsMergeStrategy:

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Read the wrapped inner error — it names the failing config section — and fix that key under the named language block.
2. Check types of language-level overrides (numbers vs strings, maps vs scalars) against the root-level equivalents.
3. Temporarily move the override to root config to confirm which language-level key breaks decoding.
4. Validate YAML/TOML syntax and indentation of the languages block.

Example fix

# before (hugo.toml)
[languages.fr.pagination]
pagerSize = "ten"
# after
[languages.fr.pagination]
pagerSize = 10

// Validate per-language config sections before load
// Each [languages.xx] block must contain only known config keys with correct types
// e.g. run: hugo config --printUnusedTemplates 2>/devev/null || hugo config
for lang, v := range cfg.GetStringMap("languages") {
    if _, ok := v.(map[string]any); !ok {
        return fmt.Errorf("languages.%s must be a table, got %T", lang, v)
    }
}

func isLangTable(v any) (map[string]any, bool) {
    m, ok := v.(map[string]any)
    return m, ok
}

if err != nil && strings.Contains(err.Error(), "failed to decode config for language") {
    // Extract the language key from the message and inspect that [languages.xx] block
    return fmt.Errorf("check the [languages.*] section named in the error for wrong types or unknown keys: %w", err)
}

When it happens

Trigger: A `[languages.<lang>]` block containing a key whose value fails its section decoder — e.g. languages.fr.pagination.pagerSize as a string, an invalid languages.<lang>.permalinks or markup structure, or a malformed params structure under a language.

Common situations: Multilingual sites where a language-level override uses the wrong type or outdated key syntax after a Hugo upgrade, copy-pasting root config into a language block incorrectly, or YAML indentation putting values under the wrong language key.

Related errors

• failed to decode languages config: %w
• failed to create config: %w
• invalid language configuration for %q
• failed to decode %q: %w
• language name cannot be empty

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/9febc21d96b7dcdd.json. Report an issue: GitHub ↗.