{"record":{"id":"e1b718b7dfcfdbf8","repo":"App-vNext/Polly","slug":"the-number-of-executions-per-timespan-must-be-posi-e1b718","errorCode":null,"errorMessage":"The number of executions per timespan must be positive.","messagePattern":"The number of executions per timespan must be positive\\.","errorType":"exception","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Polly/RateLimit/RateLimitSyntax.cs","lineNumber":49,"sourceCode":"        {\n            throw new ArgumentOutOfRangeException(nameof(numberOfExecutions), numberOfExecutions, $\"{nameof(numberOfExecutions)} per timespan must be an integer greater than or equal to 1.\");\n        }\n\n        if (perTimeSpan <= TimeSpan.Zero)\n        {\n            throw new ArgumentOutOfRangeException(nameof(perTimeSpan), perTimeSpan, $\"{nameof(perTimeSpan)} must be a positive timespan.\");\n        }\n\n        if (maxBurst < 1)\n        {\n            throw new ArgumentOutOfRangeException(nameof(maxBurst), maxBurst, $\"{nameof(maxBurst)} must be an integer greater than or equal to 1.\");\n        }\n\n        var onePer = TimeSpan.FromTicks(perTimeSpan.Ticks / numberOfExecutions);\n\n        if (onePer <= TimeSpan.Zero)\n        {\n            throw new ArgumentOutOfRangeException(nameof(perTimeSpan), perTimeSpan, \"The number of executions per timespan must be positive.\");\n        }\n\n        IRateLimiter rateLimiter = new LockFreeTokenBucketRateLimiter(onePer, maxBurst);\n\n        return new RateLimitPolicy(rateLimiter);\n    }\n}\n","sourceCodeStart":31,"sourceCodeEnd":57,"githubUrl":"https://github.com/App-vNext/Polly/blob/d0e46bdb1ee11ea50d0e4b6846d2633d6bc09bac/src/Polly/RateLimit/RateLimitSyntax.cs#L31-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"High-throughput config like thousands of executions per millisecond; integer-division flooring the per-token interval to zero; mis-scaled units (ticks vs ms).","solutions":["Increase perTimeSpan so perTimeSpan.Ticks / numberOfExecutions >= 1 tick (100ns).","Reduce numberOfExecutions so each token represents at least one tick of time.","Re-check units: TimeSpan ticks are 100ns; ensure the window is long enough."],"exampleFix":"// before\n// 10000 execs in 1 tick-window => onePer rounds to zero\nvar policy = Policy.RateLimit(10000, TimeSpan.FromTicks(1), 10000);\n// after\nvar policy = Policy.RateLimit(10000, TimeSpan.FromSeconds(1), 10000);","handlingStrategy":"validation","validationCode":"// Ensure each token is at least 1 tick (100ns)\nif (perTimeSpan.Ticks / numberOfExecutions < 1) throw new InvalidOperationException(\"perTimeSpan too short for numberOfExecutions; increase the window or lower the count.\");\nvar policy = Policy.RateLimit(numberOfExecutions, perTimeSpan, maxBurst);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the ratio perTimeSpan.Ticks / numberOfExecutions >= 1 when configuring high-throughput limits.","Remember TimeSpan granularity is 100ns (1 tick); windows under a microsecond are rarely meaningful.","Unit-test rate-limit config edge cases (very high counts, tiny windows)."],"tags":["rate-limit","argumentoutofrange","integer-overflow","token-bucket","configuration"],"backgroundTag":null,"analyzedSha":"d0e46bdb1ee11ea50d0e4b6846d2633d6bc09bac","analyzedAt":"2026-08-13T16:36:01.959Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}