Humanizr/Humanizer · critical · InvalidOperationException

Locale '{localeCode}.surfaces.calendar.months' must be a seq

Error message

Locale '{localeCode}.surfaces.calendar.months' must be a sequence of exactly 12 strings.

What it means

Thrown by AddCalendarFeatures when surfaces.calendar.months is present but is not a YAML sequence of exactly 12 entries. Month tables must cover all twelve Gregorian months with no gaps, so a shorter/longer list, a mapping, or a scalar fails the build.

Source

Thrown at src/Humanizer.SourceGenerators/Common/CanonicalLocaleAuthoring.cs:462

        }

        static void AddCalendarFeatures(
            string localeCode,
            SimpleYamlMapping calendarSurface,
            ImmutableDictionary<string, SimpleYamlValue>.Builder features)
        {
            foreach (var property in calendarSurface.Values.Keys.Where(static property => property is not ("months" or "monthsGenitive" or "hijriMonths")))
            {
                throw new InvalidOperationException(
                    $"Locale '{localeCode}.surfaces.calendar' defines unsupported property '{property}'. Supported properties: months, monthsGenitive, hijriMonths.");
            }

            var hasMonths = calendarSurface.TryGetValue("months", out var monthsValue);
            if (hasMonths)
            {
                if (monthsValue is not SimpleYamlSequence monthsSeq || monthsSeq.Items.Length != 12)
                {
                    throw new InvalidOperationException(
                        $"Locale '{localeCode}.surfaces.calendar.months' must be a sequence of exactly 12 strings.");
                }

                if (monthsSeq.Items.Any(static item => item is not SimpleYamlScalar))
                {
                    throw new InvalidOperationException(
                        $"Locale '{localeCode}.surfaces.calendar.months' items must be scalar strings.");
                }
            }

            if (calendarSurface.TryGetValue("monthsGenitive", out var monthsGenitiveValue))
            {
                if (!hasMonths)
                {
                    throw new InvalidOperationException(
                        $"Locale '{localeCode}.surfaces.calendar.monthsGenitive' requires 'months' to also be present.");
                }

View on GitHub (pinned to ffc2b77c0f)

Solutions

Provide exactly 12 string entries in surfaces.calendar.months, one per month January..December.
If a month name is unknown, copy the reference locale's list as a placeholder and translate fully before commit.
Rebuild to confirm the length guard passes.

Example fix

# before
calendar:
  months: [Janvier, Février]
# after
calendar:
  months: [Janvier, Février, Mars, Avril, Mai, Juin, Juillet, Août, Septembre, Octobre, Novembre, Décembre]

Defensive patterns

Strategy: validation

Validate before calling

# Ensure surfaces.calendar.months is a 12-element sequence.
# Parse the YAML and assert: $months -is [array] -and $months.Count -eq 12.

Prevention

Always supply exactly 12 month strings; never leave gaps.
Use a reference locale's months list as a structural template.
Build after edits to catch length mismatches early.

When it happens

Trigger: A locale YAML defines 'months: [Jan, Feb]' (too few), a mapping form, or a single string. The guard at CanonicalLocaleAuthoring.cs:460-464 requires a SimpleYamlSequence with Items.Length == 12.

Common situations: Translating only the months you had handy and deferring the rest; pasting from a source that used abbreviated forms and dropped entries; converting a mapping (month-name -> value) into the canonical sequence.

Related errors

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