crossbeam-rs/crossbeam · error

queue capacity is too large

Error message

queue capacity is too large

What it means

`ArrayQueue::new(cap)` packs head/tail lap counters into an index word; `cap + 1` rounded up to the next power of two defines one lap and must fit in the `Index` type. When that computation overflows, the queue cannot represent the requested capacity, so `new` panics with this message.

Solutions

1. Pass a smaller capacity that fits the index type
2. Clamp user/config-provided capacities to a sane maximum before `ArrayQueue::new`
3. For effectively unbounded needs, use `SegQueue` (crossbeam-queue's unbounded queue) instead

Example fix

// before
let q = ArrayQueue::new(num_items_usize_from_file_size); // may panic

// after
const MAX: usize = 1 << 30;
let q = ArrayQueue::new(cap.min(MAX).max(1));

const MAX_Q_CAP: usize = 1 << 30;
if cap == 0 || cap > MAX_Q_CAP { cap = MAX_Q_CAP; }
let q = ArrayQueue::new(cap);

When it happens

Trigger: Calling `ArrayQueue::new(cap)` with a capacity so large that `(cap + 1).next_power_of_two()` overflows the internal index integer type.

Common situations: Sizing a queue from a total workload or byte count without clamping; passing usize::MAX to mean 'effectively unbounded'; 32-bit builds receiving capacities tuned for 64-bit machines.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• bounded channel capacity is too large
• no operations have been added to `Select`
• dropped `SelectedOperation` without completing the operation
• failed to spawn scoped thread

AI-assisted analysis of crossbeam-rs/crossbeam@38dacb4622 (2026-09-13). Data as JSON: /api/errors/3e83914b51f31d5a. Report an issue: GitHub.

Appendix: source

Thrown at crossbeam-queue/src/array_queue.rs:133

        let tail = 0;

        // Allocate a buffer of `cap` slots initialized
        // with stamps.
        let buffer: Box<[Slot<T>]> = (0..cap)
            .map(|i| {
                // Set the stamp to `{ lap: 0, index: i }`.
                Slot {
                    stamp: AtomicIndex::new(i as Index),
                    value: UnsafeCell::new(MaybeUninit::uninit()),
                }
            })
            .collect();

        // One lap is the smallest power of two greater than `cap`.
        let one_lap = (cap as Index)
            .checked_add(1)
            .and_then(Index::checked_next_power_of_two)
            .expect("queue capacity is too large");

        Self {
            buffer,
            one_lap,
            head: CachePadded::new(AtomicIndex::new(head)),
            tail: CachePadded::new(AtomicIndex::new(tail)),
        }
    }

    fn push_or_else<F>(&self, mut value: T, f: F) -> Result<(), T>
    where
        F: Fn(T, Index, Index, &Slot<T>) -> Result<T, T>,
    {
        let backoff = Backoff::new();
        let mut tail = self.tail.load(Ordering::Relaxed);

        loop {
            // Deconstruct the tail.

View on GitHub (pinned to 38dacb4622)