Instrument {instrument_id} not found and `auto_load_missing_

Error message

Instrument {instrument_id} not found and `auto_load_missing_instruments` is disabled

What it means

Raised by `prepare_subscribe` when a subscription is requested for an instrument_id that is not in the client's instrument cache and the config flag `auto_load_missing_instruments` is disabled. The client refuses to subscribe because it has no instrument definition for the requested feed.

Source

Thrown at crates/adapters/derive/src/data.rs:542

        for instrument in instruments {
            self.cache_instrument(&instrument);
            if let Err(e) = self.data_sender.send(DataEvent::Instrument(instrument)) {
                log::warn!("Failed to send Derive instrument: {e}");
            }
        }
    }

    fn cache_instrument(&self, instrument: &InstrumentAny) {
        cache_instrument(&self.instruments, instrument);
    }

    fn prepare_subscribe(&self, instrument_id: InstrumentId) -> anyhow::Result<bool> {
        if self.instruments.contains_key(&instrument_id) {
            return Ok(false);
        }

        if !self.config.auto_load_missing_instruments {
            anyhow::bail!(
                "Instrument {instrument_id} not found and `auto_load_missing_instruments` is disabled"
            );
        }
        Ok(true)
    }

    async fn lazy_load_instrument(
        http_client: DeriveHttpClient,
        instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
        instrument_id: InstrumentId,
        include_expired: bool,
    ) -> anyhow::Result<()> {
        let currency = currency_from_instrument_id(&instrument_id)?;
        let definitions = fetch_instrument_definitions(&http_client, currency, include_expired)
            .await
            .with_context(|| format!("failed to lazy-load Derive instruments for {currency}"))?;
        let mut found = false;

View on GitHub (pinned to 18893faf8b)

Solutions

Set `auto_load_missing_instruments: true` in DeriveDataClientConfig so unknown instruments are fetched on demand.
Pre-load the instrument via request_instruments (with the right currencies configured) before subscribing.
Verify the InstrumentId matches a Derive-listed instrument exactly (symbol and venue).

Example fix

// before
let config = DeriveDataClientConfig { auto_load_missing_instruments: false, ..cfg };
// after
let config = DeriveDataClientConfig { auto_load_missing_instruments: true, ..cfg };

Defensive patterns

Strategy: validation

Validate before calling

// before subscribing
let known = client.instrument_cached(&instrument_id); // or track loaded ids
assert!(known || cfg.auto_load_missing_instruments,
    "enable auto_load_missing_instruments or pre-load {instrument_id}");

Try / catch

match prepare_subscribe(instrument_id) {
    Err(e) if e.to_string().contains("auto_load_missing_instruments") => {
        // enable lazy loading or fetch instrument first, then retry
    }
    r => r?,
}

Prevention

Pre-load all instruments via request_instruments at startup.
Enable auto_load_missing_instruments unless determinism is required.
Validate instrument IDs against the exchange listing before subscribing.

When it happens

Trigger: Calling subscribe_ticker_feed, subscribe_book_deltas, subscribe_book_depth10, or subscribe_trades with an InstrumentId that was never loaded into the cache while `auto_load_missing_instruments: false` in DeriveDataClientConfig.

Common situations: Explicitly disabling lazy instrument loading for determinism but requesting feeds for instruments not pre-loaded at startup; typos in instrument IDs (wrong venue or symbol case); subscribing before request_instruments completed.

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/e5b5db0c215c6dda. Report an issue: GitHub.