nautechsystems/nautilus_trader · error

Invalid depth for Binance Futures order book. Valid values

Error message

Invalid depth {depth} for Binance Futures order book. Valid values: {BINANCE_BOOK_DEPTHS:?}

What it means

The requested order book depth must be one of the Binance-supported depth levels listed in BINANCE_BOOK_DEPTHS (e.g. 5/10/20/50/100/500/1000). If not provided, depth defaults to 1000; an explicitly provided unsupported depth bails.

Solutions

1. Set cmd.depth to one of the values in BINANCE_BOOK_DEPTHS (e.g. 5, 10, 20, 50, 100, 500, 1000)
2. Remove the explicit depth to use the default 1000
3. Snap/round your configured depth to the nearest valid value before subscribing

Example fix

// before
depth: Some(NonZeroUsize::new(400).unwrap()),
// after
depth: Some(NonZeroUsize::new(500).unwrap()),

const DEPTHS: [u32; 7] = [5,10,20,50,100,500,1000];
let depth = cmd.depth.map_or(1000, |d| d.get() as u32);
assert!(DEPTHS.contains(&depth), "unsupported depth {depth}");

fn is_valid_depth(depth: Option<NonZeroUsize>) -> bool {
    const DEPTHS: [u32; 7] = [5,10,20,50,100,500,1000];
    depth.map_or(true, |d| DEPTHS.contains(&(d.get() as u32)))
}

match client.subscribe_book_deltas(cmd).await {
    Err(e) if e.to_string().contains("Invalid depth") => return Err(anyhow::anyhow!("snap depth to a valid Binance value")),
    other => other,
}

When it happens

Trigger: subscribe_book_deltas with cmd.depth set to a value not in BINANCE_BOOK_DEPTHS (e.g. 25, 400, 2000).

Common situations: Setting depth in strategy config copied from another venue's conventions, or computing depth dynamically without validating against the venue's allowed set.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid depth ; supported depths
• Binance Futures L1_MBP supports depth 1 only
• invalid Binance Futures order-book depth
• Invalid zero size for
• market-book size must be non-negative

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

Appendix: source

Thrown at crates/adapters/binance/src/futures/data.rs:1996

                *subscriptions.entry(cmd.instrument_id).or_insert(0) += 1;
            });
            self.subscribe_top_of_book(cmd.instrument_id);
            return Ok(());
        }

        if cmd.book_type != BookType::L2_MBP {
            anyhow::bail!("Binance Futures supports L1_MBP and L2_MBP order book subscriptions");
        }
        anyhow::ensure!(
            !self.l1_book_subscriptions.contains_key(&cmd.instrument_id),
            "cannot subscribe L1_MBP and L2_MBP for the same Binance Futures instrument"
        );

        let instrument_id = cmd.instrument_id;
        let depth = cmd.depth.map_or(1000, |d| d.get() as u32);

        if !BINANCE_BOOK_DEPTHS.contains(&depth) {
            anyhow::bail!(
                "Invalid depth {depth} for Binance Futures order book. \
                Valid values: {BINANCE_BOOK_DEPTHS:?}"
            );
        }

        self.book_subscriptions.insert(instrument_id, depth);

        // Bump epoch to invalidate any in-flight snapshot from a prior subscription
        let epoch = {
            let mut guard = self.book_epoch.write();
            *guard = guard.wrapping_add(1);
            *guard
        };

        self.book_buffers
            .insert(instrument_id, BookBuffer::new(epoch));

        log::debug!("OrderBook snapshot rebuild for {instrument_id} @ depth {depth} starting");

View on GitHub (pinned to 18893faf8b)