Humanizr/Humanizer · error · ArgumentOutOfRangeException

The configured profile supports magnitudes through

Error message

The configured profile supports magnitudes through {maximumMagnitude}.

What it means

Gendered joined-scale locales declare a MaximumValue (optionally +1 when AllowLongMinValue is set, so long.MinValue is representable). Magnitudes above that ceiling throw ArgumentOutOfRangeException at the top of Convert. The ceiling reflects how high the locale's scale table reaches.

Solutions

Route out-of-range values to a culture with a higher ceiling (e.g. invariant/English).
Clamp or reject oversized inputs in your own layer.
Contribute higher scales to the locale profile to raise MaximumValue.

Example fix

// before
var w = value.ToWords(GrammaticalGender.Masculine, ci);

// after — fall back for oversized values (MaximumValue is not public, so wrap defensively)
string w;
try
{
    w = value.ToWords(GrammaticalGender.Masculine, ci);
}
catch (ArgumentOutOfRangeException)
{
    w = value.ToWords(CultureInfo.InvariantCulture);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// MaximumValue is not public, so a direct pre-check is unavailable. For joined-scale gendered
// locales, wrap the call and fall back on ArgumentOutOfRangeException.

Try / catch

string words;
try
{
    words = value.ToWords(gender, ci);
}
catch (ArgumentOutOfRangeException)
{
    words = value.ToWords(CultureInfo.InvariantCulture);
}

Prevention

Record each joined-scale locale's effective ceiling from locale docs/tests.
Bound user-facing numeric inputs before localizing them.
Fall back to a high-ceiling culture for values likely to exceed authored scales.

When it happens

Trigger: value.ToWords(gender, new CultureInfo(<joined-scale culture>)) or value.ToWords(<culture>) where the absolute magnitude exceeds profile.MaximumValue (+1 if AllowLongMinValue).

Common situations: Converting very large longs (IDs, byte counts) under a locale whose authored scales stop at millions or billions.

Related errors

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

Appendix: source

Thrown at src/Humanizer/Localisation/NumberToWords/JoinedScaleNumberToWordsConverter.cs:27

/// largest value to the smallest and joins the resulting fragments with the generated separator
/// rules.
/// </remarks>
class JoinedScaleNumberToWordsConverter(JoinedScaleNumberToWordsProfile profile) : GenderedNumberToWordsConverter
{
    readonly JoinedScaleNumberToWordsProfile profile = profile;

    /// <inheritdoc/>
    public override string Convert(long number, GrammaticalGender gender, bool addAnd = true)
    {
        // `long.MinValue` is represented as one extra magnitude slot when the profile explicitly
        // allows it; everything else is bounded by the generated profile's declared ceiling.
        var magnitude = number == long.MinValue
            ? (ulong)long.MaxValue + 1
            : (ulong)Math.Abs(number);
        var maximumMagnitude = (ulong)profile.MaximumValue + (profile.AllowLongMinValue ? 1UL : 0UL);
        if (magnitude > maximumMagnitude)
        {
            throw new ArgumentOutOfRangeException(nameof(number), number, $"The configured profile supports magnitudes through {maximumMagnitude}.");
        }

        if (number == 0)
        {
            return profile.ZeroWord;
        }

        if (number < 0)
        {
            return $"{profile.MinusWord}{profile.NegativeJoinWord}{ConvertNonNegative(magnitude, gender)}";
        }

        return ConvertNonNegative((ulong)number, gender);
    }

    /// <summary>
    /// Converts the non-negative portion of a value after magnitude validation.
    /// </summary>

View on GitHub (pinned to ffc2b77c0f)