nautechsystems/nautilus_trader · error

order-book level index overflow

Error message

order-book level index overflow

What it means

Thrown when converting the per-level synthetic order ID (a `usize` level index) into the `u64` order ID required by `BookOrder::new` fails. On 64-bit platforms this is effectively unreachable; it guards a `usize`→`u64` narrowing that only fails on exotic targets.

Source

Thrown at crates/adapters/binance/src/spot/http/client.rs:3095

            anyhow::ensure!(price.is_positive(), "invalid non-positive {name} price");
            let qty_mantissa = u64::try_from(level.qty_mantissa)
                .map_err(|_| anyhow::anyhow!("invalid negative {name} quantity"))?;
            let quantity = Quantity::from_mantissa_exponent_checked(
                qty_mantissa,
                snapshot.qty_exponent,
                instrument.size_precision(),
            )
            .map_err(|e| anyhow::anyhow!("invalid {name} quantity: {e}"))?;
            anyhow::ensure!(
                quantity.is_positive(),
                "invalid non-positive {name} quantity"
            );
            let order = BookOrder::new(
                side,
                price,
                quantity,
                u64::try_from(order_id)
                    .map_err(|_| anyhow::anyhow!("order-book level index overflow"))?,
            );
            book.add(order, 0, sequence, ts_event);
            Ok(())
        };

        for (index, level) in snapshot.bids.iter().enumerate() {
            add_level(level, OrderSide::Buy, index, "bid")?;
        }
        let bid_count = snapshot.bids.len();
        for (index, level) in snapshot.asks.iter().enumerate() {
            let order_id = bid_count
                .checked_add(index)
                .ok_or_else(|| anyhow::anyhow!("order-book level index overflow"))?;
            add_level(level, OrderSide::Sell, order_id, "ask")?;
        }
        Ok(book)
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Run on a standard 64-bit platform where `usize == u64`.
2. If targeting an exotic architecture, build with a 64-bit `usize` target.
3. This is an internal invariant guard — file an issue if it reproduces on a mainstream target.

match client.request_book_snapshot(id, depth).await {
    Ok(book) => book,
    Err(e) if e.to_string().contains("level index overflow") => {
        log::error!("usize/u64 width mismatch on this target");
        Err(e)
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling `request_book_snapshot` on a platform where `usize` exceeds 64 bits (e.g. 128-bit `usize`) and the level index cannot fit in `u64`.

Common situations: Building/running on non-64-bit or unusual pointer-width targets; practically never seen on standard x86_64/aarch64 builds.

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

• Binance Spot supports L1_MBP and L2_MBP order book subscript
• Binance Spot order-book depth must be between 1 and 5000
• Binance {field} timestamp is outside the UnixNanos range: {v
• Binance user trade ID overflow during pagination
• Binance Spot L1_MBP supports depth 1 only

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/b3eb26607806c445. Report an issue: GitHub.