What causes "Locale '{localeCode}.headings.{key}' must be a sequence." in Humanizr/Humanizer?

Change the value under the named key to a YAML block sequence (one '- ' entry per heading).

Humanizr/Humanizer · error · InvalidOperationException

Locale '{localeCode}.headings.{key}' must be a sequence.

Error message

Locale '{localeCode}.headings.{key}' must be a sequence.

What it means

Each headings sub-key ('full' or 'short') must be a YAML sequence (list) of name strings. If the value under that key is a scalar or a nested mapping, the heading parser cannot iterate entries and rejects it.

Source

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

            string localeCode,
            ImmutableDictionary<string, SimpleYamlValue> features)
        {
            return !features.TryGetValue("inflection", out var inflectionValue)
                ? null
                : inflectionValue as SimpleYamlMapping
                ?? throw new InvalidOperationException($"Locale '{localeCode}.inflection' must be a mapping.");
        }

        static ImmutableArray<string> ParseHeadingSequence(SimpleYamlMapping mapping, string key, string localeCode)
        {
            if (!mapping.TryGetValue(key, out var headingValue))
            {
                throw new InvalidOperationException($"Locale '{localeCode}.headings' must define '{key}'.");
            }

            if (headingValue is not SimpleYamlSequence sequence)
            {
                throw new InvalidOperationException($"Locale '{localeCode}.headings.{key}' must be a sequence.");
            }

            if (sequence.Items.Length != 16)
            {
                throw new InvalidOperationException($"Locale '{localeCode}.headings.{key}' must contain exactly 16 entries.");
            }

            var headings = ImmutableArray.CreateBuilder<string>(16);
            for (var index = 0; index < sequence.Items.Length; index++)
            {
                if (sequence.Items[index] is not SimpleYamlScalar scalar)
                {
                    throw new InvalidOperationException($"Locale '{localeCode}.headings.{key}[{index}]' must be a scalar.");
                }

                headings.Add(scalar.Value);
            }

View on GitHub (pinned to ffc2b77c0f)

Solutions

Change the value under the named key to a YAML block sequence (one '- ' entry per heading).
Verify each line under the key starts with '- ' at the correct indent level.
Use a known-good locale file as an indentation reference.

Example fix

# before
headings:
  full: January, February

# after
headings:
  full:
    - January
    - February

Defensive patterns

Strategy: validation

Validate before calling

import yaml, pathlib
locales_dir = pathlib.Path('src/Humanizer/Locales')
for f in locales_dir.rglob('*.yml'):
    data = yaml.safe_load(f.read_text())
    if isinstance(data, dict) and isinstance(data.get('headings'), dict):
        for key in ('full', 'short'):
            val = data['headings'].get(key)
            if val is not None and not isinstance(val, list):
                print(f'{f.name}: headings.{key} must be a sequence, got {type(val).__name__}')

Prevention

Each headings sub-key must be a YAML list, not an inline scalar or mapping.
Use block sequence style ('- value') for readability and correctness.
Validate indentation so list items nest properly under each sub-key.

When it happens

Trigger: A locale sets 'headings.full:' or 'headings.short:' to a scalar string or a mapping instead of a list. For example 'full: January' instead of 'full:\n - January'.

Common situations: Inline scalar assignment instead of a list; indentation error causing the sequence items to parse as a mapping value; YAML flow-style mistakes.

Related errors

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