App-vNext/Polly · error · ArgumentOutOfRangeException

numberOfExecutions per timespan must be an integer greater t

Error message

numberOfExecutions per timespan must be an integer greater than or equal to 1.

What it means

Thrown by RateLimitSyntax.RateLimit when numberOfExecutions is less than 1. A rate limiter permitting zero executions per window would reject every call and serve no purpose, so the builder rejects it up front.

Source

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

        TimeSpan perTimeSpan) =>
        RateLimit(numberOfExecutions, perTimeSpan, 1);

    /// <summary>
    /// Builds a RateLimit <see cref="Policy"/> that will rate-limit executions to <paramref name="numberOfExecutions"/> per the timespan given.
    /// </summary>
    /// <param name="numberOfExecutions">The number of executions (call it N) permitted per timespan.</param>
    /// <param name="perTimeSpan">How often N executions are permitted.</param>
    /// <param name="maxBurst">The maximum number of executions that will be permitted in a single burst (for example if none have been executed for a while).
    /// This equates to the bucket-capacity of a token-bucket implementation.</param>
    /// <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.");
        }

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Set numberOfExecutions to at least 1.
2. Validate the config value with a fallback/default when loading from settings.
3. Guard the caller: if (rateLimit <= 0) skip building the policy.

Example fix

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

const int DefaultExecutions = 5;
var numberOfExecutions = Math.Max(1, config.GetValue("RateLimit:Executions", DefaultExecutions));
var policy = Policy.RateLimit(numberOfExecutions, perTimeSpan, maxBurst);

When it happens

Trigger: Calling Policy.RateLimit(numberOfExecutions: 0, ...) or any negative value via the sync non-generic RateLimit extension.

Common situations: Configuring rate limits from appsettings where a missing key defaults to 0; passing a computed/scaled value that rounds down to zero.

Related errors

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

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