nautechsystems/nautilus_trader · error · anyhow::Error

Futures mark price requires a BINANCE instrument

Error message

Futures mark price requires a BINANCE instrument

What it means

Subscribing to BinanceFuturesMarkPriceUpdate requires an instrument ID whose venue is BINANCE. The handler extracts the required instrument_id from the subscription metadata and rejects subscriptions for any other venue, since mark price streams are a Binance-Futures-specific data type.

Solutions

  1. Use an instrument ID with venue BINANCE for the mark price subscription
  2. Filter subscription loops so Binance-specific data types are only requested for BINANCE instruments
  3. Check the instrument ID format (e.g. BTCUSDT-PERP.BINANCE) for venue typos

Example fix

// before
subscribe("BinanceFuturesMarkPriceUpdate", "ETHUSDT-PERP.BYBIT")
// after
subscribe("BinanceFuturesMarkPriceUpdate", "ETHUSDT-PERP.BINANCE")
Defensive patterns

Strategy: validation

Validate before calling

fn can_subscribe_mark_price(instrument_id: &str) -> bool {
    instrument_id.ends_with(".BINANCE")
}

Type guard

fn is_binance_instrument(id: &InstrumentId) -> bool {
    id.venue.as_str() == "BINANCE"
}

Try / catch

if let Err(e) = client.subscribe(cmd) {
    if e.to_string().contains("requires a BINANCE instrument") {
        log::warn!("skipping non-Binance instrument for mark price");
    } else { return Err(e); }
}

Prevention

When it happens

Trigger: Calling SubscribeData for data_type "BinanceFuturesMarkPriceUpdate" with metadata instrument_id set to an instrument from a different venue (e.g. BYBIT, OKX) or an ID that failed venue parsing.

Common situations: Multi-venue strategies generically subscribing all instruments to every data type; passing a synthetic/backtest instrument ID with the wrong venue string; typos in the venue component of the instrument ID.

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


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

Appendix: source

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

    }

    fn is_connected(&self) -> bool {
        self.is_connected.load(Ordering::Relaxed)
    }

    fn is_disconnected(&self) -> bool {
        !self.is_connected()
    }

    fn subscribe(&mut self, cmd: SubscribeCustomData) -> anyhow::Result<()> {
        let data_type = cmd.data_type.type_name();
        if data_type == "BinanceFuturesTicker" {
            return subscribe_ticker(self, &cmd.data_type);
        }

        if data_type == "BinanceFuturesMarkPriceUpdate" {
            let instrument_id = Self::required_instrument_id_metadata(&cmd.data_type)?;
            anyhow::ensure!(
                instrument_id.venue == self.venue(),
                "Futures mark price requires a BINANCE instrument"
            );
            let should_subscribe = {
                let previous = self
                    .mark_price_refs
                    .load()
                    .get(&instrument_id)
                    .copied()
                    .unwrap_or(0);
                self.mark_price_refs
                    .rcu(|refs| *refs.entry(instrument_id).or_insert(0) += 1);
                previous == 0
            };

            if should_subscribe {
                let ws = self.ws_client.clone();
                let stream = format!(

View on GitHub (pinned to 18893faf8b)