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 RateLimitSyntax.RateLimit when maxBurst is less than 1. maxBurst is the token-bucket capacity; a capacity of zero would deny all traffic immediately, so it is rejected at construction.

Source

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

    /// <returns>The policy instance.</returns>
    public static RateLimitPolicy RateLimit(
        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 RateLimitPolicy(rateLimiter);
    }
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Set maxBurst to at least 1 (commonly equal to or greater than numberOfExecutions).
2. Default maxBurst to numberOfExecutions when not explicitly configured.
3. Validate burst config at load time.

Example fix

// before
var policy = Policy.RateLimit(5, TimeSpan.FromSeconds(10), 0);
// after
var policy = Policy.RateLimit(5, TimeSpan.FromSeconds(10), 5);

var maxBurst = config.GetValue("RateLimit:MaxBurst", numberOfExecutions);
if (maxBurst < 1) maxBurst = numberOfExecutions;
var policy = Policy.RateLimit(numberOfExecutions, perTimeSpan, maxBurst);

When it happens

Trigger: Calling Policy.RateLimit(n, perTimeSpan, maxBurst: 0) or a negative maxBurst on the sync non-generic overload.

Common situations: maxBurst defaulted to 0 from missing config; a separate burst setting omitted and falling back to a sentinel value of 0.

Related errors

• The number of executions per timespan must be positive.
• numberOfExecutions per timespan must be an integer greater t
• perTimeSpan must be a positive timespan.
• 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/a7c914d0e49385ac. Report an issue: GitHub.