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 non-generic BulkheadPolicy via Policy.Bulkhead(...) with maxQueuingActions < 0. The guard at BulkheadSyntax.cs:60–64 fires at construction time. A value of 0 is valid (no queuing — immediate rejection on overflow), but negative values are rejected.

Source

Thrown at src/Polly/Bulkhead/BulkheadSyntax.cs:60

    /// <para>When an execution would cause the number of actions executing concurrently through the policy to exceed <paramref name="maxParallelization" />, the policy allows a further <paramref name="maxQueuingActions" /> executions to queue, waiting for a concurrent execution slot.  When an execution would cause the number of queuing actions to exceed <paramref name="maxQueuingActions" />, a <see cref="BulkheadRejectedException" /> is thrown.</para>
    /// </summary>
    /// <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 Bulkhead(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(
            maxParallelization,
            maxQueuingActions,
            onBulkheadRejected);
    }

    private static void EmptyAction(Context context)
    {
        // No-op
    }
}

View on GitHub (pinned to d0e46bdb1e)

Solutions

1. Set maxQueuingActions to 0 or a positive integer (0 means no queue, requests are rejected immediately when parallelization is full)
2. Clamp the computed value: Math.Max(0, computedQueue)
3. Validate at startup and apply a sensible default if the value is invalid

Example fix

// before
int queue = desiredQueue - buffer; // could go negative
var policy = Policy.Bulkhead(10, queue, _ => { }); // throws if buffer > desiredQueue

// after
int queue = Math.Max(0, desiredQueue - buffer);
var policy = Policy.Bulkhead(10, queue, _ => { });

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

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

When it happens

Trigger: Calling Policy.Bulkhead(maxParallelization, maxQueuingActions, ...) where maxQueuingActions is negative. Happens when the value is parsed from configuration or computed in a way that yields a negative number.

Common situations: Subtracting a buffer from maxQueuingActions that overshoots into negatives. Configuration typo or missing key yielding a parsed negative. Off-by-one in a formula calculating queue depth.

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