App-vNext/Polly · error · ArgumentOutOfRangeException

Value must be greater than zero.

Error message

Value must be greater than zero.

What it means

Thrown by the legacy v7 async CircuitBreakerAsync<T> (generic TResult) syntax when handledEventsAllowedBeforeBreaking is <= 0. This is the number of handled results/exceptions permitted before the simple circuit opens; it must be at least 1. Fires at policy construction.

Source

Thrown at src/Polly/CircuitBreaker/AsyncCircuitBreakerTResultSyntax.cs:189

    /// </summary>
    /// <typeparam name="TResult">The return type of delegates which may be executed through the policy.</typeparam>
    /// <param name="policyBuilder">The policy builder.</param>
    /// <param name="handledEventsAllowedBeforeBreaking">The number of exceptions or handled results that are allowed before opening the circuit.</param>
    /// <param name="durationOfBreak">The duration the circuit will stay open before resetting.</param>
    /// <param name="onBreak">The action to call when the circuit transitions to an <see cref="CircuitState.Open"/> state.</param>
    /// <param name="onReset">The action to call when the circuit resets to a <see cref="CircuitState.Closed"/> state.</param>
    /// <param name="onHalfOpen">The action to call when the circuit transitions to <see cref="CircuitState.HalfOpen"/> state, ready to try action executions again. </param>
    /// <returns>The policy instance.</returns>
    /// <remarks>(see "Release It!" by Michael T. Nygard fi).</remarks>
    /// <exception cref="ArgumentOutOfRangeException">handledEventsAllowedBeforeBreaking;Value must be greater than zero.</exception>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onBreak"/> is <see langword="null"/>.</exception>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onReset"/> is <see langword="null"/>.</exception>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onHalfOpen"/> is <see langword="null"/>.</exception>
    public static AsyncCircuitBreakerPolicy<TResult> CircuitBreakerAsync<TResult>(this PolicyBuilder<TResult> policyBuilder, int handledEventsAllowedBeforeBreaking, TimeSpan durationOfBreak, Action<DelegateResult<TResult>, CircuitState, TimeSpan, Context> onBreak, Action<Context> onReset, Action onHalfOpen)
    {
        if (handledEventsAllowedBeforeBreaking <= 0)
        {
            throw new ArgumentOutOfRangeException(nameof(handledEventsAllowedBeforeBreaking), "Value must be greater than zero.");
        }

        if (durationOfBreak < TimeSpan.Zero)
        {
            throw new ArgumentOutOfRangeException(nameof(durationOfBreak), "Value must be greater than zero.");
        }

        if (onBreak == null)
        {
            throw new ArgumentNullException(nameof(onBreak));
        }

        if (onReset == null)
        {
            throw new ArgumentNullException(nameof(onReset));
        }

        if (onHalfOpen == null)

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Set handledEventsAllowedBeforeBreaking to at least 1 (commonly 3-10).
2. Validate the configured count is a positive integer at startup.
3. Use 1 if you want the circuit to open on the first handled event.

Example fix

// before
Policy.HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
    .CircuitBreakerAsync(
        handledEventsAllowedBeforeBreaking: 0,
        durationOfBreak: TimeSpan.FromSeconds(30),
        onBreak: (_, __, ___, ____) => { },
        onReset: _ => { },
        onHalfOpen: () => { });

// after
Policy.HandleResult<HttpResponseMessage>(r => !r.IsSuccessStatusCode)
    .CircuitBreakerAsync(
        handledEventsAllowedBeforeBreaking: 5,
        durationOfBreak: TimeSpan.FromSeconds(30),
        onBreak: (_, __, ___, ____) => { },
        onReset: _ => { },
        onHalfOpen: () => { });

if (handledEventsAllowedBeforeBreaking <= 0)
    throw new ArgumentOutOfRangeException(nameof(handledEventsAllowedBeforeBreaking), "Must be >= 1.");

static bool IsValidHandledEventsAllowed(int n) => n >= 1;

When it happens

Trigger: Calling Policy.HandleResult<T>(...).CircuitBreakerAsync(handledEventsAllowedBeforeBreaking: 0, ...). The check is `handledEventsAllowedBeforeBreaking <= 0`.

Common situations: Passing 0 from missing config, or intending 'always open' but using 0 instead of 1.

Related errors

• Value must be greater than zero.
• Value must be less than or equal to one.
• Value must be greater than one.
• Value must be greater than zero.
• Value must be less than or equal to one.

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