gohugoio/hugo · error

invalid language configuration for %q

Error message

invalid language configuration for %q

What it means

In `Configs.Init`, every language in the sorted base `languages` config must have a corresponding compiled per-language config in `LanguageConfigMap`. A missing entry means the merged config is internally inconsistent — a language was declared but its per-language config never compiled — so initialization aborts with this error naming the language key.

Source

Thrown at config/allconfig/allconfig.go:877

		if l.C.transientErr != nil {
			return l.C.transientErr
		}
	}
	return nil
}

func (c *Configs) IsZero() bool {
	// A config always has at least one language.
	return c == nil || len(c.Languages) == 0
}

func (c *Configs) Init(sourceFs afero.Fs, logger loggers.Logger) error {
	var languages langs.Languages

	for _, f := range c.Base.Languages.Config.Sorted {
		v, found := c.LanguageConfigMap[f.Name]
		if !found {
			return fmt.Errorf("invalid language configuration for %q", f.Name)
		}
		language, err := langs.NewLanguage(f.Name, c.Base.DefaultContentLanguage, v.TimeZone, f.LanguageConfig, logger)
		if err != nil {
			return err
		}
		languages = append(languages, language)
	}

	// Filter out disabled languages.
	var n int
	for _, l := range languages {
		if !l.Disabled {
			languages[n] = l
			n++
		}
	}
	languages = languages[:n]

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check every `[languages.X]` block for consistent, lowercase language keys across all config files and modules.
2. Consolidate language definitions into one file (e.g. `config/_default/languages.toml`) to avoid partial merges.
3. Run `hugo config` and compare the `languages` section with what you expect; remove stray or duplicated language keys.
4. If a theme/module defines languages, ensure your project either fully overrides or fully inherits them.

Example fix

# before: language declared with mismatched key casing across files
# config/_default/hugo.toml
defaultContentLanguage = "en"
# config/_default/languages.toml
[EN]
weight = 1
# after
[en]
weight = 1

for lang := range languagesConfig {
    if !langs.IsValidLanguageTag(lang) {
        return fmt.Errorf("invalid language key %q in [languages]", lang)
    }
}

cfg, err := allconfig.LoadConfig(d)
if err != nil {
    var s string
    if errors.As(err, &s); strings.Contains(err.Error(), "invalid language configuration") {
        // report which language block failed; err wraps the per-language cause
    }
    return err
}

When it happens

Trigger: A `[languages.<code>]` key present in the base config whose per-language compilation was dropped — typically caused by malformed per-language sections, conflicting language definitions across config dir files (`config/_default/languages.toml`) and modules, or invalid language codes.

Common situations: Multilingual sites splitting config across the config directory where a language appears in one file but its config fails/merges away elsewhere; case-mismatched language keys; module-mounted configs adding languages the project half-defines.

Related errors

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

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