nautechsystems/nautilus_trader · error · anyhow::Error

Instrument {symbol} not found in cache, ensure instruments l

Error message

Instrument {symbol} not found in cache, ensure instruments loaded first

What it means

BybitBybitHttpClient.instrument_from_cache() looks up an instrument in the client's local instruments_cache (populated during instrument loading) and finds none for the given symbol. Since order placement/signing helpers need instrument specs (precision, lot size), the client refuses to proceed rather than guess. It is a fail-fast cache miss, not a network error.

Source

Thrown at crates/adapters/bybit/src/http/client.rs:1793

    }

    /// Any existing instruments with the same symbols will be replaced.
    pub fn cache_instruments(&self, instruments: &[InstrumentAny]) {
        self.instruments_cache.rcu(|m| {
            for instrument in instruments {
                m.insert(instrument.symbol().inner(), instrument.clone());
            }
        });
        self.cache_initialized.store(true, Ordering::Release);
    }

    pub fn get_instrument(&self, symbol: &Ustr) -> Option<InstrumentAny> {
        self.instruments_cache.get_cloned(symbol)
    }

    fn instrument_from_cache(&self, symbol: &Symbol) -> anyhow::Result<InstrumentAny> {
        self.get_instrument(&symbol.inner()).ok_or_else(|| {
            anyhow::anyhow!(
                "Instrument {symbol} not found in cache, ensure instruments loaded first"
            )
        })
    }

    #[must_use]
    fn generate_ts_init(&self) -> UnixNanos {
        self.clock.get_time_ns()
    }

    /// Fetches the current server time from Bybit.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The request fails.
    /// - The response cannot be parsed.
    ///

View on GitHub (pinned to 18893faf8b)

Solutions

1. Ensure instruments are loaded before trading: include the symbol in your instrument provider filter (e.g. InstrumentProviderConfig with load_all or the specific symbols)
2. Call the client's instrument-loading endpoint for the relevant product type before placing orders
3. Verify the symbol string exactly matches the Bybit instrument name (e.g. BTCUSDT, BTC-28JUN24)
4. Check which product type the client was configured with; the symbol must belong to that product type's instrument set

Example fix

// before
let client = BybitHttpClient::new(...); // instruments not loaded
client.batch_place_orders(orders)?;
// after
client.load_instruments_all(product_types).await?; // populate instruments_cache
client.batch_place_orders(orders)?;

let cached = client.get_instrument(&instrument_id.symbol.inner());
if cached.is_none() {
    client.load_instruments_all(product_types).await?; // populate cache before trading
}

if client.get_instrument(&symbol.inner()).is_none() {
    return Err(format!("instrument {symbol} not loaded"));
}

match client.instrument_from_cache(&symbol) {
    Ok(instr) => proceed(instr),
    Err(e) => {
        client.load_instruments_all(product_types).await?;
        proceed(client.instrument_from_cache(&symbol)?);
    }
}

When it happens

Trigger: Calling order-related HTTP helpers (e.g. batch place order, query order) for a symbol whose instrument was never loaded into the client's instrument cache; loading instruments for a subset of product types and trading a symbol from another; symbol spelling/format mismatch (e.g. wrong case or missing suffix) so the cache key never matches.

Common situations: Starting a live/trading node with a filtered instrument provider that excludes the traded symbol; submitting orders for a newly listed instrument before instrument loading ran; typos in instrument IDs in strategy config.

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

• Lighter fill instrument {instrument_id} missing from cache
• Instrument {symbol} not found in cache
• Failed to query order {}: {}
• Instrument {symbol} not in cache
• Instrument {first_instrument_id} for the given data not foun

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