App-vNext/Polly · error · ArgumentOutOfRangeException

numberOfExecutions per timespan must be an integer greater…

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.

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

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

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

Appendix: 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)