Humanizr/Humanizer · critical · InvalidOperationException

Locale '{localeCode}.surfaces.calendar.hijriMonths' items mu

Error message

Locale '{localeCode}.surfaces.calendar.hijriMonths' items must be scalar strings.

What it means

Thrown by AddCalendarFeatures when surfaces.calendar.hijriMonths is a 12-element sequence but an item is not a YAML scalar string (e.g. a nested mapping or sequence). Hijri month names must be plain strings, and this check runs before the directionality-control check so structured items are caught first.

Source

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

                {
                    throw new InvalidOperationException(
                        $"Locale '{localeCode}.surfaces.calendar.monthsGenitive' items must be scalar strings.");
                }
            }

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

                foreach (var item in hijriSeq.Items)
                {
                    if (item is not SimpleYamlScalar scalar)
                    {
                        throw new InvalidOperationException(
                            $"Locale '{localeCode}.surfaces.calendar.hijriMonths' items must be scalar strings.");
                    }

                    if (scalar.Value.IndexOfAny(['\u200E', '\u200F', '\u061C']) >= 0)
                    {
                        throw new InvalidOperationException(
                            $"Locale '{localeCode}.surfaces.calendar.hijriMonths' must not contain directionality controls (U+200E, U+200F, U+061C).");
                    }
                }
            }

            features["calendar"] = calendarSurface;
        }

        static string NormalizeCanonicalText(string value)
        {
            var normalized = value.Replace("\r\n", "\n");
            normalized = normalized.TrimEnd('\n') + "\n";

View on GitHub (pinned to ffc2b77c0f)

Solutions

Flatten every Hijri month entry to a plain scalar string.
Confirm each item is inline like '- Muharram' or an inline '[...]' list, not a nested block.
Rebuild to confirm the scalar-items check passes.

Example fix

# before
calendar:
  hijriMonths:
    - name: Muharram
# after
calendar:
  hijriMonths: [Muharram, Safar, Rabi al-Awwal, Rabi al-Thani, Jumada al-Awwal, Jumada al-Thani, Rajab, Shaban, Ramadan, Shawwal, Dhu al-Qidah, Dhu al-Hijjah]

Defensive patterns

Strategy: validation

Validate before calling

# Ensure every hijriMonths item is a scalar string, not a nested object.
# After parsing: $hijri | ForEach-Object { $_ -is [string] }.

Prevention

Flatten Hijri month entries to plain strings; do not wrap names in objects.
Use inline sequence form to avoid indentation-induced mappings.
Build after edits to surface the offending item before the directionality check runs.

When it happens

Trigger: A Hijri month entry is a nested object or sub-list. The loop at CanonicalLocaleAuthoring.cs:502-507 checks each item with 'item is not SimpleYamlScalar' and throws.

Common situations: Pasting CLDR objects that wrap names in metadata; mis-indenting list items into mappings; converting from a structured calendar source.

Related errors

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