App-vNext/Polly · error · ArgumentOutOfRangeException

maxBurst must be an integer greater than or equal to 1.

Error message

maxBurst must be an integer greater than or equal to 1.

What it means

Thrown by the typed RateLimitAsync<TResult> overload when maxBurst is less than 1. maxBurst is the token-bucket capacity; a non-positive capacity makes the limiter perpetually reject. Same guard as the factory-less overload.

Source

Thrown at src/Polly/RateLimit/AsyncRateLimitTResultSyntax.cs:78

    public static AsyncRateLimitPolicy<TResult> RateLimitAsync<TResult>(
        int numberOfExecutions,
        TimeSpan perTimeSpan,
        int maxBurst,
        Func<TimeSpan, Context, TResult>? retryAfterFactory)
    {
        if (numberOfExecutions < 1)
        {
            throw new ArgumentOutOfRangeException(nameof(numberOfExecutions), numberOfExecutions, $"{nameof(numberOfExecutions)} per timespan must be an integer greater than or equal to 1.");
        }

        if (perTimeSpan <= TimeSpan.Zero)
        {
            throw new ArgumentOutOfRangeException(nameof(perTimeSpan), perTimeSpan, $"{nameof(perTimeSpan)} must be a positive timespan.");
        }

        if (maxBurst < 1)
        {
            throw new ArgumentOutOfRangeException(nameof(maxBurst), maxBurst, $"{nameof(maxBurst)} must be an integer greater than or equal to 1.");
        }

        var onePer = TimeSpan.FromTicks(perTimeSpan.Ticks / numberOfExecutions);

        if (onePer <= TimeSpan.Zero)
        {
            throw new ArgumentOutOfRangeException(nameof(perTimeSpan), perTimeSpan, "The number of executions per timespan must be positive.");
        }

        IRateLimiter rateLimiter = new LockFreeTokenBucketRateLimiter(onePer, maxBurst);

        return new AsyncRateLimitPolicy<TResult>(rateLimiter, retryAfterFactory);
    }
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Set maxBurst to a positive integer (>= numberOfExecutions for no burst suppression).
2. Clamp config: Math.Max(1, parsed).
3. Use maxBurst = numberOfExecutions when you want to disallow bursts rather than 0.
4. Validate the full config triple at startup.

Example fix

// before
var p = Policy.RateLimitAsync<int>(10, TimeSpan.FromSeconds(1), 0, null);

// after
var p = Policy.RateLimitAsync<int>(10, TimeSpan.FromSeconds(1), 10, null);

int burst = Math.Max(1, parsedMaxBurst);
var p = Policy.RateLimitAsync<TResult>(n, perTimeSpan, burst, retryAfterFactory);

When it happens

Trigger: Calling Policy.RateLimitAsync<TResult>(n, ts, 0, factory) or with a negative maxBurst. The retryAfterFactory is irrelevant to this check.

Common situations: maxBurst from an optional config key defaulting to 0; mis-copy of a config template omitting the value; intent to suppress bursts implemented as 0 instead of maxBurst = numberOfExecutions.

Related errors

• numberOfExecutions per timespan must be an integer greater t
• perTimeSpan must be a positive timespan.
• The number of executions per timespan must be positive.
• numberOfExecutions per timespan must be an integer greater t
• perTimeSpan must be a positive timespan.

AI-assisted analysis of App-vNext/Polly@d0e46bdb1e (2026-08-13). Data as JSON: /api/errors/f43f072ca5131245. Report an issue: GitHub.