App-vNext/Polly · error · ArgumentOutOfRangeException

Value must be equal to or greater than {resolutionOfCircuit.

Error message

Value must be equal to or greater than {resolutionOfCircuit.TotalMilliseconds} milliseconds. This is the minimum resolution of the CircuitBreaker timer.

What it means

Thrown by AdvancedCircuitBreaker<T> when samplingDuration is below the circuit timer's minimum resolution of 20 milliseconds (ResolutionOfCircuitTimer = TimeSpan.FromMilliseconds(20).Ticks). The advanced breaker divides samplingDuration into windows, so it cannot operate below that resolution. Fires at policy build time.

Source

Thrown at src/Polly/CircuitBreaker/AdvancedCircuitBreakerTResultSyntax.cs:238

        Action<DelegateResult<TResult>, CircuitState, TimeSpan, Context> onBreak,
        Action<Context> onReset,
        Action onHalfOpen)
    {
        var resolutionOfCircuit = TimeSpan.FromTicks(AdvancedCircuitController<EmptyStruct>.ResolutionOfCircuitTimer);

        if (failureThreshold <= 0)
        {
            throw new ArgumentOutOfRangeException(nameof(failureThreshold), "Value must be greater than zero.");
        }

        if (failureThreshold > 1)
        {
            throw new ArgumentOutOfRangeException(nameof(failureThreshold), "Value must be less than or equal to one.");
        }

        if (samplingDuration < resolutionOfCircuit)
        {
            throw new ArgumentOutOfRangeException(nameof(samplingDuration), $"Value must be equal to or greater than {resolutionOfCircuit.TotalMilliseconds} milliseconds. This is the minimum resolution of the CircuitBreaker timer.");
        }

        if (minimumThroughput <= 1)
        {
            throw new ArgumentOutOfRangeException(nameof(minimumThroughput), "Value must be greater than one.");
        }

        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)

View on GitHub (pinned to d0e46bdb1e)

Solutions

Use a samplingDuration of at least 20ms; in practice prefer 1-30 seconds for meaningful throughput measurement.
Sanity-check the configured duration against TimeSpan.FromMilliseconds(20) before building the policy.
Verify config units (seconds vs milliseconds) are what the API expects.

Example fix

// before
.AdvancedCircuitBreaker(
    failureThreshold: 0.5,
    samplingDuration: TimeSpan.FromMilliseconds(5),
    ...)

// after
.AdvancedCircuitBreaker(
    failureThreshold: 0.5,
    samplingDuration: TimeSpan.FromSeconds(10),
    ...)

Defensive patterns

Strategy: validation

Validate before calling

if (samplingDuration < TimeSpan.FromMilliseconds(20))
    throw new ArgumentOutOfRangeException(nameof(samplingDuration), "samplingDuration must be >= 20ms.");

Type guard

static bool IsValidSamplingDuration(TimeSpan d) => d >= TimeSpan.FromMilliseconds(20);

Prevention

Verify config units (seconds vs milliseconds) before binding.
Never pass TimeSpan.Zero as a placeholder; use a real value.
Prefer seconds-scale sampling windows for production traffic.

When it happens

Trigger: Calling AdvancedCircuitBreaker(..., samplingDuration: TimeSpan.FromMilliseconds(10), ...) or TimeSpan.Zero or a negative duration. The check is `samplingDuration < resolutionOfCircuit` where resolutionOfCircuit == 20ms.

Common situations: Passing TimeSpan.Zero as a placeholder, misconfiguring the unit (e.g. supplying milliseconds where seconds were intended yields an accidentally tiny window), or reading a 0/default value from config.

Related errors

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