nautechsystems/nautilus_trader · error

MBO delta index overflow

Error message

MBO delta index overflow

What it means

This panic comes from the MBO (market-by-order) delta buffer in the Databento decoder. Each buffered delta gets a monotonically increasing u64 index via `checked_add`; the `.expect` fires if that counter would wrap past u64::MAX, which would silently corrupt delta ordering. The library throws it as a hard invariant because delta sequence integrity is essential for correct order-book reconstruction.

Source

Thrown at crates/adapters/databento/src/decode/market_data.rs:250

    queue: VecDeque<QueuedMboDelta>,
    tail: Option<(InstrumentId, u64)>,
    tails: AHashMap<InstrumentId, u64>,
    head: u64,
    next: u64,
}

impl MboDeltaBuffer {
    pub(crate) fn push(
        &mut self,
        msg: &dbn::MboMsg,
        instrument_id: InstrumentId,
        delta: Option<OrderBookDelta>,
    ) {
        if let Some(delta) = delta {
            self.release(instrument_id, 0);

            let index = self.next;
            self.next = self.next.checked_add(1).expect("MBO delta index overflow");
            let ready = msg.flags.is_last();
            self.queue.push_back(QueuedMboDelta { delta, ready });

            if !ready
                && let Some((tail_instrument_id, tail)) = self.tail.replace((instrument_id, index))
            {
                self.tails.insert(tail_instrument_id, tail);
            }
        } else if msg.flags.is_last() {
            self.release(instrument_id, dbn::flags::LAST);
        }
    }

    pub(crate) fn pop_ready(&mut self) -> Option<OrderBookDelta> {
        if !self.queue.front().is_some_and(|queued| queued.ready) {
            return None;
        }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Restart the data feed / drop and recreate the decoder so the buffer's `next` counter resets.
2. Audit for a buffer instance being kept alive far longer than one subscription session and recreate it per session.
3. If legitimately near the limit, switch the counter type to u128 in the buffer implementation.

When it happens

Trigger: Pushing more than u64::MAX deltas through a single long-lived `MboDeltaBuffer` instance without ever resetting it — i.e. after 2^64 `push` calls on the same stream state.

Common situations: In practice only reachable in extremely long-running live feeds, a leaked/never-dropped buffer reused across many sessions, or a bug elsewhere that repeatedly re-creates decoding state while sharing the buffer. It is effectively unreachable in normal use.

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

• DurationNanos overflow in from_micros
• {e}
• window index fits u32
• subscription generation overflow
• heartbeat request timeout should fit in an instant

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