Humanizr/Humanizer · error · ArgumentOutOfRangeException

Specified argument was out of the range of valid values. (Pa

Error message

Specified argument was out of the range of valid values. (Parameter 'casing')

What it means

Thrown in the flags-enum branch of Humanize<T> when a LetterCasing value is supplied that is not defined. Because flags enums humanize each flag separately and apply casing per flag, the method checks Enum.IsDefined(flagsCasing) inside the TreatAsFlags path and throws ArgumentOutOfRangeException named 'casing'. This fires only for [Flags] enums and only when a casing argument was provided.

Source

Thrown at src/Humanizer/EnumHumanizeExtensions.cs:146

        Humanize(input, null, EnumHumanizeSource.Default);

    static string Humanize<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicFields)] T>(
        T input,
        LetterCasing? casing,
        EnumHumanizeSource source)
        where T : struct, Enum
    {
        if (!Enum.IsDefined(source))
        {
            throw new ArgumentOutOfRangeException(nameof(source));
        }

        var (zero, values) = EnumCache<T>.GetInfo(source);
        if (EnumCache<T>.TreatAsFlags(input, source))
        {
            if (casing is { } flagsCasing && !Enum.IsDefined(flagsCasing))
            {
                throw new ArgumentOutOfRangeException(nameof(casing));
            }

            // Avoid LINQ allocations by manually iterating and building the list
            List<string>? flagValues = null;
            foreach (var value in values)
            {
                if (value.CompareTo(zero) != 0 && input.HasFlag(value))
                {
                    flagValues ??= new List<string>();
                    var flag = EnumCache<T>.GetHumanized(value, source);
                    flagValues.Add(casing is { } flagCasing && !flag.IsMetadata ? flag.Text.ApplyCase(flagCasing) : flag.Text);
                }
            }

            return flagValues?.Humanize() ?? string.Empty;
        }

        var humanizedEnum = EnumCache<T>.GetHumanized(input, source);

View on GitHub (pinned to ffc2b77c0f)

Solutions

Guard the casing with Enum.IsDefined(casing) before calling Humanize on a flags enum.
Centralize casing selection into a validated option so only defined LetterCasing values propagate.
If you do not need a specific casing for flags, call the parameterless Humanize() to bypass the check entirely.

Example fix

// before
var text = perms.Humanize((LetterCasing)styleCode);

// after
var casing = Enum.IsDefined(typeof(LetterCasing), styleCode)
    ? (LetterCasing)styleCode
    : (LetterCasing?)null;
var text = casing is { } c ? perms.Humanize(c) : perms.Humanize();

Defensive patterns

Strategy: validation

Validate before calling

if (casing.HasValue && !Enum.IsDefined(typeof(LetterCasing), casing.Value))
    throw new ArgumentOutOfRangeException(nameof(casing));
var text = perms.Humanize(casing!.Value);

Type guard

static bool IsValidCasing(LetterCasing c) => Enum.IsDefined(typeof(LetterCasing), c);

Try / catch

try { return perms.Humanize(casing); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "casing")
{ return perms.Humanize(); }

Prevention

Validate LetterCasing once at the boundary and reuse the checked value.
For flags enums where casing is optional, pass the parameterless overload when unsure.
Keep casing selection in a single validated option object.

When it happens

Trigger: Calling (Permission.Read | Permission.Write).Humanize((LetterCasing)7) where Permission is a [Flags] enum; passing an invalid LetterCasing to a flags humanization that also set a non-null casing. Non-flags enums do not reach this specific throw.

Common situations: Sharing a single 'style' setting across both flags and non-flags humanization where the style int can drift out of the [0..3] range; deserializing the casing from config as an int; default(LetterCasing) is Title (0) and is valid, so an unset field will not trigger this.

Related errors

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