nautechsystems/nautilus_trader · error · InstrumentLookupError

instrument not found in cache: {instrument_id}

Error message

instrument not found in cache: {instrument_id}

What it means

subscribe_bars looks up the instrument for the bar's instrument_id in the client's local instruments cache before registering the WebSocket candle subscription. If the instrument was never loaded into the cache (instruments not requested at startup, or an unknown/synthetic symbol), it raises an InstrumentLookupError::not_found instead of subscribing blindly.

Source

Thrown at crates/adapters/hyperliquid/src/data.rs:992

        Ok(())
    }

    fn subscribe_funding_rates(&mut self, cmd: SubscribeFundingRates) -> anyhow::Result<()> {
        let ws = self.ws_client.clone();
        let instrument_id = cmd.instrument_id;

        self.spawn_task("subscribe_funding_rates", async move {
            ws.subscribe_funding_rates(instrument_id).await
        });

        Ok(())
    }

    fn subscribe_bars(&mut self, subscription: SubscribeBars) -> anyhow::Result<()> {
        let instrument_id = subscription.bar_type.instrument_id();
        if !self.instruments.contains_key(&instrument_id) {
            anyhow::bail!(InstrumentLookupError::not_found(instrument_id));
        }

        let bar_type = subscription.bar_type;
        let ws = self.ws_client.clone();

        self.spawn_task("subscribe_bars", async move {
            ws.subscribe_bars(bar_type).await
        });

        Ok(())
    }

    fn unsubscribe_instrument(&mut self, _cmd: &UnsubscribeInstrument) -> anyhow::Result<()> {
        // `subscribe_instrument` only emits the cached instrument; it opens no
        // venue channel, so there is nothing to tear down here.
        Ok(())
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Request/subscribe to the instrument (subscribe_instruments) or ensure the client loaded all Hyperliquid instruments before subscribing to bars.
2. Verify the instrument_id exactly matches a tradable Hyperliquid symbol including venue suffix.
3. Check for typos or stale instrument definitions in strategy config; reload instruments after listing changes.

Example fix

// before
self.data_engine.subscribe_bars(bar_type) // instrument never loaded
// after
self.data_engine.subscribe_instruments(); // ensure cache populated first
self.data_engine.subscribe_bars(bar_type);

if !client.instrument_ids().contains(&bar_type.instrument_id()) {
    return Err(format!("{} not loaded; subscribe instruments first", bar_type.instrument_id()));
}

When it happens

Trigger: Calling subscribe_bars with a bar_type whose instrument_id is absent from self.instruments — e.g. subscribing to bars for an instrument not requested during instrument initialization, or a typo'd/synthetic instrument id.

Common situations: Strategies subscribing to bars on instruments that exist on other venues but not Hyperliquid; symbol format mismatches (wrong suffix/venue in the instrument id); skipping the instruments subscription at client start; replay data referencing stale instruments.

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

• Invalid Hyperliquid bar interval: {s}
• Unsupported minute step: {step}
• Unsupported hour step: {step}
• Unsupported day step: {step}
• Hyperliquid does not support {a:?} aggregation

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