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

AsyncBulkheadTResultSyntax.BulkheadAsync<TResult> throws ArgumentOutOfRangeException(nameof(maxQueuingActions)) when maxQueuingActions < 0. Generic legacy bulkhead mirror of the non-generic check: the queue may be zero but not negative.

Source

Thrown at src/Polly/Bulkhead/AsyncBulkheadTResultSyntax.cs:63

    /// </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="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<TResult> BulkheadAsync<TResult>(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<TResult>(
            maxParallelization,
            maxQueuingActions,
            onBulkheadRejectedAsync);
    }

    private static Task EmptyHandler(Context context) => TaskHelper.EmptyTask;
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Pass maxQueuingActions >= 0 (0 disables queuing).
2. Clamp: Math.Max(0, configured).
3. Validate at the configuration boundary.

Example fix

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

// after
var policy = Policy<string>.BulkheadAsync(5, maxQueuingActions: 0);

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

When it happens

Trigger: Calling Policy<T>.BulkheadAsync(5, maxQueuingActions: -1) or any negative value.

Common situations: Config sentinel of -1 misread as 'default'; arithmetic that subtracts from queue length; unvalidated user input.

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