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 RateLimitSyntax.RateLimit when the derived per-token interval onePer (perTimeSpan.Ticks / numberOfExecutions) rounds down to zero or below. This happens when the window is too short relative to the execution count for a single tick of granularity.

Source

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

        {
            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. Increase perTimeSpan so perTimeSpan.Ticks / numberOfExecutions >= 1 tick (100ns).
2. Reduce numberOfExecutions so each token represents at least one tick of time.
3. Re-check units: TimeSpan ticks are 100ns; ensure the window is long enough.

Example fix

// before
// 10000 execs in 1 tick-window => onePer rounds to zero
var policy = Policy.RateLimit(10000, TimeSpan.FromTicks(1), 10000);
// after
var policy = Policy.RateLimit(10000, TimeSpan.FromSeconds(1), 10000);

// Ensure each token is at least 1 tick (100ns)
if (perTimeSpan.Ticks / numberOfExecutions < 1) throw new InvalidOperationException("perTimeSpan too short for numberOfExecutions; increase the window or lower the count.");
var policy = Policy.RateLimit(numberOfExecutions, perTimeSpan, maxBurst);

When it happens

Trigger: A combination where perTimeSpan.Ticks / numberOfExecutions equals zero — e.g. numberOfExecutions=5 with perTimeSpan shorter than 5 ticks, or a very large execution count against a small window.

Common situations: High-throughput config like thousands of executions per millisecond; integer-division flooring the per-token interval to zero; mis-scaled units (ticks vs ms).

Related errors

• 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
• perTimeSpan must be a positive timespan.
• 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/e1b718b7dfcfdbf8. Report an issue: GitHub.