What causes "Inflection {subject} contains invalid Unicode." in Humanizr/Humanizer?

Inspect the offending YAML value for invalid Unicode — use a hex editor or Unicode inspector to find lone surrogates.

Humanizr/Humanizer · error · InvalidOperationException

Inflection {subject} contains invalid Unicode.

Error message

Inflection {subject} contains invalid Unicode.

What it means

The validator attempts NFC normalization of authored text and catches ArgumentException. If normalization fails — typically because the string contains unpaired UTF-16 surrogates or other invalid Unicode sequences — the error is rethrown with a descriptive message naming the subject that failed.

Source

Thrown at src/Humanizer.SourceGenerators/Generators/ProfileCatalogs/InflectionCatalogValidation.cs:232

        static string NormalizeAuthoredText(
            string value,
            string casing,
            ImmutableArray<string> ownerScripts,
            string subject,
            bool allowStemPlaceholder,
            bool allowNonLetters)
        {
            string normalized;
            try
            {
                normalized = value.IsNormalized(NormalizationForm.FormC)
                    ? value
                    : value.Normalize(NormalizationForm.FormC);
            }
            catch (ArgumentException)
            {
                throw new InvalidOperationException(
                    $"Inflection {subject} contains invalid Unicode.");
            }

            if (casing == "lower-title-upper")
            {
                if (!TryNormalizeSimpleLower(normalized, out var lower))
                {
                    throw new InvalidOperationException(
                        $"Inflection {subject} has an unsupported casing expansion.");
                }

                normalized = lower;
            }

            var literal = allowStemPlaceholder
                ? normalized.Replace("{stem}", string.Empty)
                : normalized;
            if (literal.Length > 0 &&

View on GitHub (pinned to ffc2b77c0f)

Solutions

Inspect the offending YAML value for invalid Unicode — use a hex editor or Unicode inspector to find lone surrogates.
Replace the malformed sequence with the correct character (e.g., use the precomposed form or a proper surrogate pair).
Re-save the locale YAML file as UTF-8 without BOM using a reliable editor to eliminate encoding corruption.

Example fix

# before — contains lone high surrogate U+D800
accepted:
  - 'word\uD800'
# after
accepted:
  - 'word'

Defensive patterns

Strategy: validation

Validate before calling

# Before building, scan locale YAML for strings with invalid Unicode (lone surrogates).
python3 -c "
import yaml, sys
for f in sys.argv[1:]:
    raw = open(f, encoding='utf-8').read()
    for i, ch in enumerate(raw):
        cp = ord(ch)
        if 0xD800 <= cp <= 0xDFFF:
            print(f'{f}: lone surrogate U+{cp:04X} at position {i}')
" src/Humanizer/Locales/*.yml

Prevention

Always save locale YAML as well-formed UTF-8 without lone surrogates.
Avoid pasting text from terminals or tools that may corrupt encoding.
Run a Unicode validation script in CI that rejects files with lone surrogates.

When it happens

Trigger: An authored text value in the locale YAML contains a malformed Unicode sequence that causes value.Normalize(NormalizationForm.FormC) to throw ArgumentException. This happens with lone surrogate halves (U+D800-U+DFFF without their pair) or other ill-formed code unit sequences.

Common situations: Pasting text from an external tool that introduced lone surrogates. Encoding issues when saving the YAML file (wrong BOM, mojibake). Manual editing that accidentally inserts a surrogate-half character.

Related errors

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