Humanizr/Humanizer · error · InvalidOperationException

Locale '{localeCode}' is not defined.

Error message

Locale '{localeCode}' is not defined.

What it means

Thrown by ResolveLocale when a locale is referenced (typically via an 'inherits'/'variantOf' parent) but no locale file defines that code. Inheritance targets must exist in the catalog. Surfaced as compiler diagnostic HSG003 (severity Error).

Source

Thrown at src/Humanizer.SourceGenerators/Common/LocaleYamlCatalog.cs:452

        static LocaleDefinition ParseLocaleDefinition(string localeCode, string fileText)
        {
            var document = CanonicalLocaleAuthoring.Parse(localeCode, fileText);
            return CanonicalLocaleAuthoring.ToLocaleDefinition(document);
        }

        static ResolvedLocaleDefinition ResolveLocale(
            string localeCode,
            Dictionary<string, LocaleDefinition> parsedLocales,
            HashSet<string> resolving,
            ImmutableArray<ResolvedLocaleDefinition>.Builder cache,
            ImmutableArray<Diagnostic>.Builder diagnostics)
        {
            if (cache.FirstOrDefault(cached => cached.LocaleCode == localeCode) is { } cached)
                return cached;

            if (!parsedLocales.TryGetValue(localeCode, out var locale))
            {
                throw new InvalidOperationException($"Locale '{localeCode}' is not defined.");
            }

            if (!resolving.Add(localeCode))
            {
                throw new InvalidOperationException($"Locale inheritance cycle detected at '{localeCode}'.");
            }

            ResolvedLocaleDefinition inherited;
            if (string.IsNullOrWhiteSpace(locale.Inherits))
            {
                inherited = ResolvedLocaleDefinition.Empty(localeCode);
            }
            else
            {
                var inheritedLocale = locale.Inherits!;
                if (!parsedLocales.ContainsKey(inheritedLocale))
                {
                    diagnostics.Add(Diagnostic.Create(

View on GitHub (pinned to ffc2b77c0f)

Solutions

1. Verify the parent code in the message matches an existing file name (without extension) under src/Humanizer/Locales.
2. Correct the inherits/variantOf value to the real parent code, or add the missing parent file.
3. Check casing: locale codes are compared ordinally, so fr-FR does not match fr-fr.
4. Rebuild to confirm the HSG003 diagnostic clears.

Example fix

# before (file src/Humanizer/Locales/fr-FR.yml)
inherits: fr-CA
# after (no fr-CA.yml exists; inherit from fr instead)
inherits: fr

# Collect every inherits/variantOf target and confirm a matching file exists.
codes=$(find src/Humanizer/Locales -name '*.yml' -printf '%f\n' | sed 's/\.yml$//' | sort -u)
grep -rhoE '^(inherits|variantOf):\s*.*' src/Humanizer/Locales | awk '{print $2}' | sort -u | while read parent; do
  echo "$codes" | grep -qxF "$parent" || echo "MISSING PARENT: $parent"
done

When it happens

Trigger: A locale file sets inherits: <parent> (or variantOf) to a code that has no corresponding file, e.g. inherits: fr-FR when only fr.yml exists, or a typo like inherits: en-US.

Common situations: Author renames a parent locale without updating children; typo in the inherits value; referencing a not-yet-added locale; case mismatch between the inherits value and the file name.

Related errors

• Phrase '{path}' must define forms, 'symbol', or 'template'.
• Phrase '{path}' must define forms.
• Phrase '{path}' must define 'numeric', 'text', or 'words'.
• Phrase forms '{path}' must define at least one form.
• Phrase '{path}.countPlacement' uses unsupported count placem

AI-assisted analysis of Humanizr/Humanizer@ffc2b77c0f (2026-08-13). Data as JSON: /api/errors/ea19f9896c53f341. Report an issue: GitHub.