microsoft/aspire · error · ArgumentOutOfRangeException

Must be in the range

Error message

Must be in the range: [{min}{minMessage}, {max}{maxMessage}]

What it means

Thrown by Guard.ThrowIfOutOfRange (Range helper) in the vendored ConfluentKafka instrumentation's Guard when a numeric argument falls outside the inclusive/exclusive bounds passed by the caller. It throws ArgumentOutOfRangeException carrying the parameter name, the offending value, and a composed message describing the allowed range (bracket style indicates inclusivity). Typically guards timeouts, sizes, and quantities.

Solutions

1. Read the allowed range from the exception message and clamp or correct the argument to be within it.
2. Fix the configuration source (appsettings/env var) that supplied the out-of-range value.
3. Validate ranges at your own boundary with ArgumentOutOfRangeException.ThrowIfOutOfRange-style checks before calling.

Example fix

// before
var timeout = TimeSpan.FromSeconds(config.GetValue("Timeout", -1));
SetTimeout(timeout);

// after
var seconds = config.GetValue("Timeout", 30);
ArgumentOutOfRangeException.ThrowIfLessThan(seconds, 1);
SetTimeout(TimeSpan.FromSeconds(seconds));

if (value < min || value > max)
{
    throw new ArgumentOutOfRangeException(nameof(value), value, $"Must be in the range [{min}, {max}]");
}

try
{
    instrumented.SetTimeout(timeout);
}
catch (ArgumentOutOfRangeException ex)
{
    logger.LogError(ex, "timeout {Value} outside allowed range: {Message}", ex.ActualValue, ex.Message);
}

When it happens

Trigger: Calling a guarded API with a value outside the documented range, e.g. a negative or zero timeout, a period longer than the allowed maximum, or a value that must be exclusive-bounded and exactly equals the boundary.

Common situations: Configuration values like sampling period, batch size, or timeout loaded as -1 or 0 from config; units mistakes (milliseconds vs seconds) pushing values past max; boundary values that violate exclusive bounds.

Related errors

• Must not be null
• Must not be null or empty
• Must not be null or whitespace
• Must not be zero
• Cannot cast ' ' from ' ' to

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/36ec40ef232ec851. Report an issue: GitHub.

Appendix: source

Thrown at src/Vendoring/OpenTelemetry.Instrumentation.ConfluentKafka/Shared/Guard.cs:201

        }

        [DebuggerHidden]
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private static void Range<T>(T value, string? paramName, T min, T max, string? minName, string? maxName, string? message)
            where T : IComparable<T>
        {
            if (value.CompareTo(min) < 0 || value.CompareTo(max) > 0)
            {
                var minMessage = minName != null ? $": {minName}" : string.Empty;
                var maxMessage = maxName != null ? $": {maxName}" : string.Empty;
                var exMessage = message ?? string.Format(
                    CultureInfo.InvariantCulture,
                    "Must be in the range: [{0}{1}, {2}{3}]",
                    min,
                    minMessage,
                    max,
                    maxMessage);
                throw new ArgumentOutOfRangeException(paramName, value, exMessage);
            }
        }
    }
}

View on GitHub (pinned to 25830f84bd)