microsoft/aspire · error · ArgumentOutOfRangeException

Must not be negative

Error message

Must not be negative

What it means

Guard.ThrowIfNegative validates that an int argument is not negative, throwing ArgumentOutOfRangeException with 'Must not be negative'. The StackExchangeRedis instrumentation uses it to reject negative counts, timeouts, or sizes early with a clear parameter name captured from the caller's expression via CallerArgumentExpression.

Solutions

1. Fix the value so it is >= 0 before the call.
2. Clamp with Math.Max(0, value) if negative is expected from arithmetic.
3. Validate configuration inputs at startup so negatives never reach the call.
4. Check upstream arithmetic (subtraction/overflow) that produced the negative number.

Example fix

// before
Guard.ThrowIfNegative(maxRetries); // computed value was -1
// after
maxRetries = Math.Max(0, maxRetries);
Guard.ThrowIfNegative(maxRetries);

if (value < 0) throw new ArgumentOutOfRangeException(nameof(value), value, "must be >= 0");

catch (ArgumentOutOfRangeException ex) when (ex.ParamName == paramName) { value = Math.Max(0, value); }

When it happens

Trigger: Calling Guard.ThrowIfNegative(value) or APIs that use it, with a negative int value.

Common situations: Computing a delta/remaining count that went negative; misconfigured timeout or batch size; integer overflow wrapping to negative.

Related errors

• Must be in the range
• Must not be zero
• Address prefix must be a string or a parameter resource…
• Address prefix must be omitted, a string, or a parameter…
• Ago must be at least 1 minute to be compatible with acr…

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

Appendix: source

Thrown at src/Vendoring/OpenTelemetry.Instrumentation.StackExchangeRedis/Shared/Guard.cs:147

            {
                throw new ArgumentException(message, paramName);
            }
#endif
        }

        /// <summary>
        /// Throw an exception if the value is negative.
        /// </summary>
        /// <param name="value">The value to check.</param>
        /// <param name="message">The message to use in the thrown exception.</param>
        /// <param name="paramName">The parameter name to use in the thrown exception.</param>
        [DebuggerHidden]
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static void ThrowIfNegative(int value, string message = "Must not be negative", [CallerArgumentExpression(nameof(value))] string? paramName = null)
        {
            if (value < 0)
            {
                throw new ArgumentOutOfRangeException(paramName, message);
            }
        }

        /// <summary>
        /// Throw an exception if the value is not considered a valid timeout.
        /// </summary>
        /// <param name="value">The value to check.</param>
        /// <param name="paramName">The parameter name to use in the thrown exception.</param>
        [DebuggerHidden]
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static void ThrowIfInvalidTimeout(int value, [CallerArgumentExpression(nameof(value))] string? paramName = null)
        {
            ThrowIfOutOfRange(value, paramName, min: Timeout.Infinite, message: $"Must be non-negative or '{nameof(Timeout)}.{nameof(Timeout.Infinite)}'");
        }

        /// <summary>
        /// Throw an exception if the value is not within the given range.
        /// </summary>

View on GitHub (pinned to 25830f84bd)