App-vNext/Polly · error · ArgumentOutOfRangeException

Value must be greater than or equal to zero.

Error message

Value must be greater than or equal to zero.

What it means

Thrown as ArgumentOutOfRangeException(nameof(maxQueuingActions)) when constructing a generic BulkheadPolicy<TResult> via Policy.Bulkhead<TResult>(...) with maxQueuingActions < 0. The guard at BulkheadTResultSyntax.cs:64–68 fires at construction time. Zero is valid (no queue); negative values are rejected.

Source

Thrown at src/Polly/Bulkhead/BulkheadTResultSyntax.cs:64

    /// </summary>
    /// <typeparam name="TResult">The type of the result.</typeparam>
    /// <param name="maxParallelization">The maximum number of concurrent actions that may be executing through the policy.</param>
    /// <param name="maxQueuingActions">The maximum number of actions that may be queuing, waiting for an execution slot.</param>
    /// <param name="onBulkheadRejected">An action to call, if the bulkhead rejects execution due to oversubscription.</param>
    /// <returns>The policy instance.</returns>
    /// <exception cref="ArgumentOutOfRangeException">maxParallelization;Value must be greater than zero.</exception>
    /// <exception cref="ArgumentOutOfRangeException">maxQueuingActions;Value must be greater than or equal to zero.</exception>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="onBulkheadRejected"/> is <see langword="null"/>.</exception>
    public static BulkheadPolicy<TResult> Bulkhead<TResult>(int maxParallelization, int maxQueuingActions, Action<Context> onBulkheadRejected)
    {
        if (maxParallelization <= 0)
        {
            throw new ArgumentOutOfRangeException(nameof(maxParallelization), "Value must be greater than zero.");
        }

        if (maxQueuingActions < 0)
        {
            throw new ArgumentOutOfRangeException(nameof(maxQueuingActions), "Value must be greater than or equal to zero.");
        }

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

        return new BulkheadPolicy<TResult>(
            maxParallelization,
            maxQueuingActions,
            onBulkheadRejected);
    }
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Ensure maxQueuingActions is 0 or positive (0 disables the queue entirely)
2. Clamp the value: Math.Max(0, computedQueueDepth)
3. Validate and log at startup before constructing the policy

Example fix

// before
int queueDepth = baseQueue - reserveSlots; // may be negative
var policy = Policy.Bulkhead<string>(10, queueDepth, _ => { }); // throws

// after
int queueDepth = Math.Max(0, baseQueue - reserveSlots);
var policy = Policy.Bulkhead<string>(10, queueDepth, _ => { });

int safeQueue = Math.Max(0, maxQueuingActions);
var policy = Policy.Bulkhead<TResult>(maxParallelization, safeQueue, onReject);

public static bool IsValidQueueDepth(int value) => value >= 0;

When it happens

Trigger: Calling Policy.Bulkhead<TResult>(maxParallelization, maxQueuingActions, ...) where maxQueuingActions is negative. Happens when the queue depth is computed or configured to a negative value.

Common situations: Arithmetic on queue depth that overshoots into negatives. Configuration key missing or misparsed to a negative number. Inheriting a queue-size formula from a non-generic context that produces different results.

Related errors

• Value must be greater than zero.
• Value must be greater than zero.
• Value must be greater than or equal to zero.
• Value cannot be null.
• Value cannot be null.

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