nautechsystems/nautilus_trader · error

Instrument not found in cache: {symbol}

Error message

Instrument not found in cache: {symbol}

What it means

Thrown by BinanceFuturesHttpClient::get_size_precision when the symbol (derived from the InstrumentId via format_binance_symbol) has no entry in the client's in-memory instruments DashMap cache. The cache is populated when instruments are fetched/defined during client or actor initialization; requesting order reports for a symbol never loaded means the quantity precision needed to build Quantity values is unavailable, so the method fails fast rather than guessing a precision.

Source

Thrown at crates/adapters/binance/src/futures/http/client.rs:2672

                    None
                }
            }
        } else {
            None
        };

        Ok(Some(BinanceFuturesAlgoOrderQueryResult {
            algo: order,
            actual,
        }))
    }

    /// Returns the size precision for an instrument from the cache.
    fn get_size_precision(&self, symbol: &str) -> anyhow::Result<u8> {
        let instrument = self
            .instruments
            .get(&Ustr::from(symbol))
            .ok_or_else(|| anyhow::anyhow!("Instrument not found in cache: {symbol}"))?;

        let precision = match instrument.value() {
            BinanceFuturesInstrument::UsdM(s) => s.quantity_precision,
            BinanceFuturesInstrument::CoinM(s) => s.quantity_precision,
        };

        Ok(precision as u8)
    }

    /// Returns the price precision for an instrument from the cache.
    fn get_price_precision(&self, symbol: &str) -> anyhow::Result<u8> {
        let instrument = self
            .instruments
            .get(&Ustr::from(symbol))
            .ok_or_else(|| anyhow::anyhow!("Instrument not found in cache: {symbol}"))?;

        let precision = match instrument.value() {
            BinanceFuturesInstrument::UsdM(s) => s.price_precision,

View on GitHub (pinned to a4b06ed870)

Solutions

  1. Load/await the instrument definitions for the market before requesting order or fill reports (populate the cache the client was constructed with)
  2. Verify the InstrumentId: correct venue (BINANCE_PERP vs BINANCE_COINM), correct quote currency, and a symbol Binance actually lists
  3. If the instrument was recently delisted, stop requesting reports for it and clear residual state
  4. Confirm you are using the matching client type for the market type (USD-M client for USDT/USDC pairs, Coin-M client for coin-margined pairs)

Example fix

// before
let fills = client.request_fill_reports(/* ... */).await?; // cache empty

// after
client.request_instruments(None).await?; // populate instrument cache first
let fills = client.request_fill_reports(/* ... */).await?;
Defensive patterns

Strategy: validation

Validate before calling

if client.get_size_precision(&symbol).is_err() {
    client.request_instruments(None).await?; // ensure cache populated
}
let precision = client.get_size_precision(&symbol)?;

Try / catch

Catch the anyhow error mentioning "Instrument not found in cache", trigger an instrument reload once, and only then retry the report request.

Prevention

When it happens

Trigger: Calling request_order_status_reports / request_fill_reports (which call get_size_precision) before the instrument definitions for that market have been loaded into the client; using a symbol whose formatting does not match the cached key (the cache is keyed by the formatted base symbol string, e.g. 'BTCUSDT'); a delisted or misspelled instrument; USD-M symbol sent to a Coin-M client.

Common situations: Backtest or live nodes that fetch instruments lazily after the first report request; typos in InstrumentId symbols; instruments delisted by Binance between session start and report generation; skipping the instrument-loading step in custom wiring of the HTTP client.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@a4b06ed870 (2026-08-16). Data as JSON: /api/errors/7e35f37615ff5d0c. Report an issue: GitHub.