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 RateLimitAsync when maxBurst is less than 1. maxBurst is the bucket capacity (maximum executions permitted in a single burst after idle); zero or negative capacity makes the limiter unable to ever permit execution. This is the third sequential config guard.

Source

Thrown at src/Polly/RateLimit/AsyncRateLimitSyntax.cs:42

    /// <returns>The policy instance.</returns>
    public static AsyncRateLimitPolicy RateLimitAsync(
        int numberOfExecutions,
        TimeSpan perTimeSpan,
        int maxBurst)
    {
        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(rateLimiter);
    }
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Set maxBurst to a positive integer (often equal to or greater than numberOfExecutions).
2. Clamp the config value: Math.Max(1, parsedBurst).
3. If you want to forbid bursts, set maxBurst = numberOfExecutions rather than 0.
4. Validate the full (numberOfExecutions, perTimeSpan, maxBurst) triple before constructing the policy.

Example fix

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

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

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

When it happens

Trigger: Calling Policy.RateLimitAsync(n, ts, 0) or with a negative maxBurst. Typically the value is derived from configuration without a lower bound.

Common situations: maxBurst sourced from an optional config key that defaults to 0; intentional 'disable burst' set to 0 not realizing it fully blocks execution; copying a config template that omitted the value.

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/7ee764e1859a0a1d. Report an issue: GitHub.