crossbeam-rs/crossbeam · error

bounded channel capacity is too large

Error message

bounded channel capacity is too large

What it means

The bounded (array-based) channel stores a mark bit and lap counter inside a single packed index word. The capacity plus one must fit as a power of two within the `Index` type; `checked_next_power_of_two`/`checked_mul` failing means the requested capacity is too large for the internal index representation, so the constructor panics instead of silently wrapping.

Solutions

1. Reduce the requested capacity to a value that fits the index type (practically, far below usize::MAX — e.g. cap at a few million)
2. Validate/clamp user- or config-supplied capacity before calling `bounded(cap)`
3. If huge capacity is truly needed, use an unbounded channel or a different data structure

Example fix

// before
let cap: usize = std::env::var("CAP").unwrap().parse().unwrap();
let (tx, rx) = crossbeam_channel::bounded(cap); // may panic

// after
let cap: usize = std::env::var("CAP").unwrap().parse().unwrap();
const MAX_CAP: usize = 1 << 30;
let (tx, rx) = crossbeam_channel::bounded(cap.min(MAX_CAP).max(1));

const MAX_BOUNDED_CAP: usize = 1 << 30;
assert!(cap > 0 && cap <= MAX_BOUNDED_CAP, "capacity out of range");
let (tx, rx) = crossbeam_channel::bounded(cap);

When it happens

Trigger: Calling `bounded::<Index>(cap)` (e.g. `crossbeam_channel::bounded(cap)`) with a capacity so large that `cap + 1` rounded up to the next power of two, or that value times two, overflows the internal `Index` integer type.

Common situations: Passing `usize::MAX` or a user/CLI-supplied capacity without bounds; config value in bytes accidentally used as item count; computing capacity from a buffer size and overflowing on 32-bit platforms.

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

• queue 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/6cacbc4b63a78bbd. Report an issue: GitHub.

Appendix: source

Thrown at crossbeam-channel/src/flavors/array.rs:117

    mark_bit: Index,

    /// Senders waiting while the channel is full.
    senders: SyncWaker,

    /// Receivers waiting while the channel is empty and not disconnected.
    receivers: SyncWaker,
}

impl<T> Channel<T> {
    /// Creates a bounded channel of capacity `cap`.
    pub(crate) fn with_capacity(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be positive");

        // Use checked arithmetic before computing `mark_bit` and `one_lap`.
        let mark_bit = (cap as Index)
            .checked_add(1)
            .and_then(Index::checked_next_power_of_two)
            .expect("bounded channel capacity is too large");
        let one_lap = mark_bit
            .checked_mul(2)
            .expect("bounded channel capacity is too large");

        // Head is initialized to `{ lap: 0, mark: 0, index: 0 }`.
        let head = 0;
        // Tail is initialized to `{ lap: 0, mark: 0, index: 0 }`.
        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, mark: 0, index: i }`.
                Slot {
                    stamp: AtomicIndex::new(i as Index),
                    msg: UnsafeCell::new(MaybeUninit::uninit()),
                }

View on GitHub (pinned to 38dacb4622)