Humanizr/Humanizer · critical · InvalidOperationException

Locale '{localeCode}.surfaces.calendar' defines unsupported

Error message

Locale '{localeCode}.surfaces.calendar' defines unsupported property '{property}'. Supported properties: months, monthsGenitive, hijriMonths.

What it means

Thrown by AddCalendarFeatures when surfaces.calendar in a locale YAML contains a property other than the three allowed keys: months, monthsGenitive, hijriMonths. The calendar surface is closed, so any extra key (e.g. 'weekdays', 'quarters') is rejected at build time.

Source

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

            {
                if (dateOnlyValue is not SimpleYamlMapping dateOnlyMapping)
                {
                    throw new InvalidOperationException(
                        $"Locale '{localeCode}.surfaces.ordinal.dateOnly' must be a mapping, not a scalar or sequence.");
                }

                features["dateOnlyToOrdinalWords"] = dateOnlyMapping;
            }
        }

        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.");
                }
            }

View on GitHub (pinned to ffc2b77c0f)

Solutions

  1. Remove the unsupported property '{property}' from surfaces.calendar.
  2. Keep only months, monthsGenitive, and/or hijriMonths, ensuring each is a 12-element sequence of strings.
  3. If a new calendar dimension is genuinely required, extend AddCalendarFeatures and SupportedSurfaceNames in the generator before adding YAML.

Example fix

# before
calendar:
  months: [...]
  weekdays: [...]
# after
calendar:
  months: [...]
Defensive patterns

Strategy: validation

Validate before calling

# Validate calendar surface keys against the allow-list.
$allowed = 'months','monthsGenitive','hijriMonths'
# Parse the locale YAML and assert every key under surfaces.calendar is in $allowed.

Prevention

When it happens

Trigger: A contributor adds an unsupported calendar key like 'weekdays' or 'seasons' under surfaces.calendar. The allow-list loop at CanonicalLocaleAuthoring.cs:451-456 flags it and throws.

Common situations: Migrating from CLDR data that includes many calendar dimensions; pasting calendar config from another library; adding locale-specific calendar data not yet modeled by the schema.

Related errors

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