What causes "Instrument {symbol} not found in cache" in nautechsystems/nautilus_trader?

Initialize/load the instrument provider (call the client's initialize/load instruments) before requesting order books.

Instrument {symbol} not found in cache

Error message

Instrument {symbol} not found in cache

What it means

`request_order_book` (book snapshot via `get_book`) requires the target instrument to already exist in the client's local instrument cache; `get_instrument(&symbol)` returning None raises "Instrument {symbol} not found in cache". The adapter refuses to build an order book for a symbol it has no parsed instrument definition for.

Source

Thrown at crates/adapters/architect_ax/src/http/client.rs:1520

    }

    /// Requests an order book snapshot from Ax and builds a Nautilus [`OrderBook`].
    ///
    /// Requires the instrument to be cached.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The instrument is not found in the cache.
    /// - The HTTP request fails.
    pub async fn request_book_snapshot(
        &self,
        symbol: Ustr,
        depth: Option<usize>,
    ) -> anyhow::Result<OrderBook> {
        let instrument = self
            .get_instrument(&symbol)
            .ok_or_else(|| anyhow::anyhow!("Instrument {symbol} not found in cache"))?;

        let resp = self
            .inner
            .get_book(symbol, Some(2))
            .await
            .map_err(|e| anyhow::anyhow!(e))?;

        let instrument_id = instrument.id();
        let mut book = OrderBook::new(instrument_id, BookType::L2_MBP);

        let price_precision = instrument.price_precision();
        let size_precision = instrument.size_precision();
        let ts_event = ax_timestamp_stn_to_unix_nanos(resp.book.ts, resp.book.tn)?;

        for (i, level) in resp.book.b.iter().enumerate() {
            if depth.is_some_and(|d| i >= d) {
                break;
            }

View on GitHub (pinned to 18893faf8b)

Solutions

Initialize/load the instrument provider (call the client's initialize/load instruments) before requesting order books.
Verify the symbol matches the cached instrument exactly (use the InstrumentId/Ustr obtained from the provider, not a hand-built string).
Confirm the instrument is currently listed on AX; refresh instruments if it was newly listed.
If the symbol should exist, check for whitespace/case differences in the configured symbol.

Example fix

// before
client.request_order_book("btcusdt-perp".into(), Some(10)).await?; // not in cache

// after
client.initialize().await?; // loads instruments into cache
let instrument_id = InstrumentId::from("BTCUSDT-PERP.AX");
client.request_order_book(instrument_id.symbol.as_ustr(), Some(10)).await?;

Defensive patterns

Strategy: validation

Validate before calling

// before request_order_book
client.initialize().await?; // ensures instruments are cached
if client.get_instrument(&symbol).is_none() {
    eprintln!("{symbol} not cached; loading instruments first");
    // reload instrument provider or abort subscription
}

Try / catch

match client.request_order_book(symbol, Some(10)).await {
    Ok(book) => book,
    Err(e) if e.to_string().contains("not found in cache") => {
        client.initialize().await?; // (re)load instruments, then retry once
        client.request_order_book(symbol, Some(10)).await?
    }
    Err(e) => return Err(e),
}

Prevention

Always call the client's initialize/instrument-load step before any data requests.
Subscribe using InstrumentIds obtained from the provider, not hand-built symbol strings.
On startup, log cached symbols so mismatches are visible immediately.
Refresh the instrument cache when subscribing to newly listed instruments.

When it happens

Trigger: Calling `request_order_book(symbol, depth)` before the instrument provider has been loaded/initialized, or with a symbol string that doesn't exactly match a cached AX instrument (case/format mismatch, delisted instrument).

Common situations: Subscribing to order book data before `initialize()` loaded instruments; using an exchange-native symbol variant that differs from the cached Ustr; stale cache after an instrument was delisted.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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