dotnet/reactive · error · ArgumentOutOfRangeException

Specified argument was out of the range of valid values…

Error message

Specified argument was out of the range of valid values. (Parameter 'capacity')

What it means

SchedulerQueue<TAbsolute>'s constructor validates that the initial capacity is non-negative and throws ArgumentOutOfRangeException naming 'capacity'. The capacity is forwarded to the underlying PriorityQueue, which cannot allocate with a negative size.

Solutions

Pass 0 or a positive capacity
Clamp computed capacity with Math.Max(0, computed)
Fix the source of the negative number (config default, subtraction underflow)

Example fix

// before
int capacity = expectedCount - reservedCount; // can be negative
var queue = new SchedulerQueue<DateTimeOffset>(capacity);
// after
int capacity = Math.Max(0, expectedCount - reservedCount);
var queue = new SchedulerQueue<DateTimeOffset>(capacity);

Defensive patterns

Strategy: validation

Validate before calling

if (capacity < 0) capacity = 0;

Type guard

static bool IsValidCapacity(int c) => c >= 0;

Try / catch

try { var q = new SchedulerQueue<DateTimeOffset>(capacity); }
catch (ArgumentOutOfRangeException) { var q = new SchedulerQueue<DateTimeOffset>(0); }

Prevention

Clamp computed sizes with Math.Max(0, x)
Avoid -1 sentinels flowing into capacity parameters
Assert capacity bounds in configuration parsing

When it happens

Trigger: new SchedulerQueue<DateTimeOffset>(-1); a computed capacity that underflowed (e.g. size - reserved); copying a default(-1)-like value from config.

Common situations: Integer arithmetic producing negative capacity; uninitialized config values interpreted as -1; porting code from collections that allowed -1.

Related errors

AI-assisted analysis of dotnet/reactive@94b5d5ab91 (2026-09-15). Data as JSON: /api/errors/f8ef05d61d439872. Report an issue: GitHub.

Appendix: source

Thrown at Rx.NET/Source/src/System.Reactive/Concurrency/SchedulerQueue.cs:35

        /// <summary>
        /// Creates a new scheduler queue with a default initial capacity.
        /// </summary>
        public SchedulerQueue()
            : this(1024)
        {
        }

        /// <summary>
        /// Creates a new scheduler queue with the specified initial capacity.
        /// </summary>
        /// <param name="capacity">Initial capacity of the scheduler queue.</param>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="capacity"/> is less than zero.</exception>
        public SchedulerQueue(int capacity)
        {
            if (capacity < 0)
            {
                throw new ArgumentOutOfRangeException(nameof(capacity));
            }

            _queue = new PriorityQueue<ScheduledItem<TAbsolute>>(capacity);
        }

        /// <summary>
        /// Gets the number of scheduled items in the scheduler queue.
        /// </summary>
        public int Count => _queue.Count;

        /// <summary>
        /// Enqueues the specified work item to be scheduled.
        /// </summary>
        /// <param name="scheduledItem">Work item to be scheduled.</param>
        public void Enqueue(ScheduledItem<TAbsolute> scheduledItem) => _queue.Enqueue(scheduledItem);

        /// <summary>
        /// Removes the specified work item from the scheduler queue.

View on GitHub (pinned to 94b5d5ab91)