Humanizr/Humanizer · error · ArgumentOutOfRangeException

The configured profile supports values from {profile.Minimum

Error message

The configured profile supports values from {profile.MinimumValue} through {profile.MaximumValue}.

What it means

Turkic-family locales bound to the harmony-based converter (e.g. kk, ky, tr, uz) declare an authored [MinimumValue, MaximumValue] range reflecting how many scales the locale actually has words for. Values outside that range throw ArgumentOutOfRangeException before decomposition. The range is a property of the generated profile, not a fixed library constant.

Source

Thrown at src/Humanizer/Localisation/NumberToWords/HarmonyOrdinalNumberToWordsConverter.cs:32

/// </summary>
class HarmonyOrdinalNumberToWordsConverter(HarmonyOrdinalNumberToWordsProfile profile) : GenderlessNumberToWordsConverter
{
    /// <summary>
    /// Immutable generated profile that owns the decimal-scale lexicon and harmony rules.
    /// </summary>
    readonly HarmonyOrdinalNumberToWordsProfile profile = profile;

    /// <summary>
    /// Converts the given value using the locale's harmony-based cardinal rules.
    /// </summary>
    /// <param name="input">The number to convert.</param>
    /// <returns>The localized cardinal words for <paramref name="input"/>.</returns>
    /// <exception cref="ArgumentOutOfRangeException"><paramref name="input"/> is outside the configured profile range.</exception>
    public override string Convert(long input)
    {
        if (input > profile.MaximumValue || input < profile.MinimumValue)
        {
            throw new ArgumentOutOfRangeException(
                nameof(input),
                input,
                $"The configured profile supports values from {profile.MinimumValue} through {profile.MaximumValue}.");
        }

        // The cardinal path shares one recursive engine for all supported magnitudes; the
        // profile decides the exact hundred behavior. Keeping the sign outside the magnitude
        // decomposition makes long.MinValue representable without overflowing.
        var words = ConvertCore(GetAbsoluteValue(input), allowExactHundredWord: true);
        return input < 0 ? $"{profile.MinusWord} {words}" : words;
    }

    // Composite counts recurse through the same decimal-scale engine; only the generated
    // hundred/ordinal strategies vary per locale.
    /// <summary>
    /// Converts a number using the shared decimal decomposition while honoring the requested
    /// exact-hundred behavior.
    /// </summary>

View on GitHub (pinned to ffc2b77c0f)

Solutions

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

Example fix

// before
var w = value.ToWords(new CultureInfo("tr"));

// after — fall back for oversized values (ceiling is locale-specific, so wrap defensively)
string w;
try
{
    w = value.ToWords(new CultureInfo("tr"));
}
catch (ArgumentOutOfRangeException)
{
    w = value.ToWords(CultureInfo.InvariantCulture);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// MaximumValue/MinimumValue are not public, so a direct pre-check is unavailable.
// For Turkic locales, wrap the call and fall back on ArgumentOutOfRangeException:
// (see tryCatchPattern)

Try / catch

string words;
try
{
    words = value.ToWords(new CultureInfo("tr"));
}
catch (ArgumentOutOfRangeException)
{
    words = value.ToWords(CultureInfo.InvariantCulture);
}

Prevention

Record each Turkic locale's effective ceiling from the 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(new CultureInfo("ky")) where value > profile.MaximumValue or value < profile.MinimumValue. Fires at the top of Convert(long).

Common situations: Converting very large longs (population figures, astronomical values, IDs) under a Turkic culture 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/7c3dcad99a5ab81a. Report an issue: GitHub.