nautechsystems/nautilus_trader · error

Lighter fill instrument

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.

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();
Defensive patterns

Strategy: validation

Validate before calling

// 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}");
}

Try / catch

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); }
}

Prevention

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

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

Appendix: 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)