nautechsystems/nautilus_trader · error

Lighter fill instrument {instrument_id} missing from cache

Error message

Lighter fill instrument {instrument_id} missing from cache

What it means

The fill's market_id mapped to a registered instrument_id, but the corresponding Instrument definition is missing from the core cache. The registry knows the venue market, yet the cache layer (populated by instrument loading/subscription) does not hold the instrument needed to parse the fill into a report.

Source

Thrown at crates/adapters/lighter/src/execution.rs:5286

                        "Lighter get_trades failed (market_id={:?}, account_index={}, cursor={:?}): {}",
                        query.market_id,
                        credential.account_index(),
                        cursor,
                        scrub_auth(&format!("{e:#}")),
                    );
                    return Err(anyhow::Error::new(e).context("failed to fetch Lighter fills"));
                }
            };

            for trade in &response.trades {
                let Some(instrument_id) = self.registry.instrument_id(trade.market_id) else {
                    anyhow::bail!(
                        "no Lighter instrument registered for fill market_index={}",
                        trade.market_id,
                    );
                };
                let Some(instrument) = self.core.cache().instrument(&instrument_id).cloned() else {
                    anyhow::bail!("Lighter fill instrument {instrument_id} missing from cache");
                };

                match parse_ws_fill_report(
                    trade,
                    credential.account_index(),
                    &instrument,
                    self.core.account_id,
                    ts_init,
                ) {
                    Ok(Some(report)) => {
                        if cmd.start.is_some_and(|start| report.ts_event < start)
                            || cmd.end.is_some_and(|end| report.ts_event > end)
                        {
                            continue;
                        }

                        // Mass-status reconciliation must surface the original
                        // Nautilus cloid, not the venue's numeric echo.

View on GitHub (pinned to 18893faf8b)

Solutions

1. Ensure instruments are loaded into the cache before enabling fills fetching
2. Reload instruments into the cache (re-run instrument initialization)
3. Retry the fills fetch after cache warm-up completes
4. Report/fix the registry-vs-cache inconsistency if it persists across restarts

Example fix

// before: start fills polling immediately
client.spawn_fills_poller();
// after: wait until cache has the instruments
client.load_instruments_to_cache().await;
client.spawn_fills_poller();

// ensure the cache is warm before fills processing
for id in client.registry.instrument_ids() {
    assert!(client.core.cache().instrument(&id).is_some(), "cache missing {id}");
}

if let Err(e) = client.fetch_fills().await {
    if e.to_string().contains("missing from cache") {
        client.load_instruments_to_cache().await;
        client.fetch_fills().await?;
    } else { return Err(e); }
}

When it happens

Trigger: Processing a fetched fill whose instrument was registered in the adapter registry but never added to (or evicted from) the core cache — partial startup, cache cleared mid-session, or a race between fills fetching and cache population.

Common situations: Fills fetching racing instrument cache warm-up at startup, a cache invalidation/reset during the session, or instrument load errors that left the registry and cache inconsistent.

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

• Instrument {symbol} not found in cache
• Instrument {symbol} not found in cache, ensure instruments l
• Instrument {symbol} not in cache
• Instrument {first_instrument_id} for the given data not foun
• venue-leg quantity calculation validated cumulative fills

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