App-vNext/Polly · error · ArgumentOutOfRangeException

The number of executions per timespan must be positive.

Error message

The number of executions per timespan must be positive.

What it means

Thrown by the typed RateLimitAsync<TResult> overload when the derived per-execution interval (perTimeSpan.Ticks / numberOfExecutions) rounds down to zero ticks. Same edge case as the factory-less variant: a high execution count against a window with fewer ticks than executions produces a sub-tick interval that cannot be represented.

Source

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

        {
            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. Widen perTimeSpan or reduce numberOfExecutions so perTimeSpan.Ticks >= numberOfExecutions.
2. Express the rate in executions-per-second with a one-second window.
3. Validate the derived interval before constructing the policy.
4. For sub-tick rates, migrate to Polly v8 (Polly.RateLimiting backed by System.Threading.RateLimiting).

Example fix

// before
// 1 tick / 5 executions = 0 -> throws
var p = Policy.RateLimitAsync<int>(5, TimeSpan.FromTicks(1), 5, null);

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

if (perTimeSpan.Ticks < numberOfExecutions)
    throw new ArgumentOutOfRangeException(nameof(perTimeSpan), "perTimeSpan must have at least one tick per execution");
var p = Policy.RateLimitAsync<TResult>(numberOfExecutions, perTimeSpan, maxBurst, retryAfterFactory);

When it happens

Trigger: Configuring RateLimitAsync<TResult>(n, perTimeSpan, burst, factory) where perTimeSpan.Ticks < numberOfExecutions. The retryAfterFactory does not affect this arithmetic guard.

Common situations: Very high rates against tiny windows; mis-scaled units (per-second counts on per-millisecond windows); dynamically-scaled execution counts that outgrow the window's tick resolution.

Related errors

• perTimeSpan must be a positive timespan.
• perTimeSpan must be a positive timespan.
• The number of executions per timespan must be positive.
• numberOfExecutions per timespan must be an integer greater t
• maxBurst must be an integer greater than or equal to 1.

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