nautechsystems/nautilus_trader · error · anyhow::Error

Binance Futures instrument {instrument_id} is not loaded for

Error message

Binance Futures instrument {instrument_id} is not loaded for reconciliation

What it means

For order reconciliation, query_order needs each instrument's price/size precision; get_instrument_precision looks the instrument up in the HTTP client's instrument_reconciliation cache and errors with this message when the instrument is absent. It means the Binance Futures instrument was never loaded into the client before an order query/reconciliation.

Source

Thrown at crates/adapters/binance/src/futures/execution.rs:980

        self.http_client
            .close_listen_key(key.expose_secret())
            .await
            .with_context(|| context.to_string())?;
        let mut owned = slot.write();
        if owned.as_ref().map(SecretString::expose_secret) == Some(key.expose_secret()) {
            *owned = None;
        }
        Ok(())
    }

    /// Returns the (price_precision, size_precision) for an instrument.
    fn get_instrument_precision(&self, instrument_id: InstrumentId) -> anyhow::Result<(u8, u8)> {
        self.http_client
            .instrument_reconciliation(&instrument_id)
            .map(|instrument| (instrument.price_precision(), instrument.size_precision()))
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "Binance Futures instrument {instrument_id} is not loaded for reconciliation"
                )
            })
    }

    fn is_instrument_out_of_scope(&self, instrument_id: InstrumentId) -> bool {
        let provider = &self.config.instrument_provider;
        !provider.load_all
            && provider.load_ids.as_ref().is_some_and(|load_ids| {
                load_ids
                    .iter()
                    .all(|raw_id| InstrumentId::from(raw_id.as_str()) != instrument_id)
            })
    }

    /// Creates a position status report from Binance position risk data.
    fn create_position_report(
        &self,

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Add the instrument to the instrument provider load scope (e.g. load_ids containing the instrument) before connecting
  2. Ensure instruments are loaded/initialized (await initialization) before submitting or reconciling orders
  3. Verify the instrument_id symbol and venue exactly match a Binance Futures symbol (e.g. BTCUSDT-PERP.BINANCE)
  4. Cache the instrument in the client's reconciliation instruments prior to query_order

Example fix

// before
config = BinanceFuturesExecClientConfig(instrument_provider=InstrumentProviderConfig(load_all=False))
// after
config = BinanceFuturesExecClientConfig(
    instrument_provider=InstrumentProviderConfig(load_ids=[InstrumentId.from_str("BTCUSDT-PERP.BINANCE")])
)  # ensure the traded instrument is loaded before reconciliation
Defensive patterns

Strategy: validation

Validate before calling

if client.instrument_reconciliation(&instrument_id).is_none() {
    return Err(anyhow::anyhow!("{instrument_id} not loaded; add it to the provider load scope"));
}

Try / catch

match client.query_order(&instrument_id, &client_order_id) {
    Err(e) if e.to_string().contains("is not loaded for reconciliation") => {
        eprintln!("load {instrument_id} before querying orders: {e}");
    }
    other => other?,
}

Prevention

When it happens

Trigger: Calling query_order (or triggering reconciliation) for an instrument_id that was not added to the client — e.g. order events referencing an instrument added after connect, or a symbol not included in the configured instrument provider load scope.

Common situations: Loading only a subset of instruments (load_all=false with limited filters) but trading/reconciling symbols outside that set; or submitting/restoring orders on a freshly added symbol before instruments finish loading.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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