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

AsyncBulkheadSyntax.BulkheadAsync throws ArgumentOutOfRangeException(nameof(maxQueuingActions)) when maxQueuingActions < 0. The queue may be empty (0 = no queuing, reject-on-overflow) but never negative; a negative queue length is meaningless.

Source

Thrown at src/Polly/Bulkhead/AsyncBulkheadSyntax.cs:70

    /// <param name="maxQueuingActions">The maximum number of actions that may be queuing, waiting for an execution slot.</param>
    /// <param name="onBulkheadRejectedAsync">An action to call asynchronously, 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="onBulkheadRejectedAsync"/> is <see langword="null"/>.</exception>
    public static AsyncBulkheadPolicy BulkheadAsync(
        int maxParallelization,
        int maxQueuingActions,
        Func<Context, Task> onBulkheadRejectedAsync)
    {
        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 (onBulkheadRejectedAsync == null)
        {
            throw new ArgumentNullException(nameof(onBulkheadRejectedAsync));
        }

        return new AsyncBulkheadPolicy(
            maxParallelization,
            maxQueuingActions,
            onBulkheadRejectedAsync);
    }
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Pass maxQueuingActions >= 0 (use 0 to disable queuing).
2. Clamp config values: maxQueuingActions = Math.Max(0, configured).
3. Validate input at the configuration boundary.

Example fix

// before
var policy = Policy.BulkheadAsync(5, maxQueuingActions: -1);

// after
var policy = Policy.BulkheadAsync(5, maxQueuingActions: 0); // no queue

if (maxQueuingActions < 0) {
    throw new ArgumentOutOfRangeException(nameof(maxQueuingActions), "Use zero or a positive value.");
}

When it happens

Trigger: Calling Policy.BulkheadAsync(maxParallelization: 5, maxQueuingActions: -1) or any negative queue size.

Common situations: Config binding that yields -1 as a 'use default' sentinel; arithmetic that subtracts from the queue size; passing an int parsed from user input without bounds checking.

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/c15581b118a13a8a. Report an issue: GitHub.