nautechsystems/nautilus_trader · error

Instrument {} missing from cache for position report

Error message

Instrument {} missing from cache for position report

What it means

This error is raised by the OKX HTTP adapter when building position reports: an instrument referenced by an OKX position (`inst_id`) could not be resolved from the local instrument cache, so a complete report cannot be produced. The adapter refuses to guess missing instrument metadata and aborts the position-report generation instead of emitting partial data.

Source

Thrown at crates/adapters/okx/src/http/client.rs:5395

            .get_positions(params)
            .await
            .map_err(|e| anyhow::anyhow!(e))?;

        let ts_init = self.generate_ts_init();
        let mut reports = Vec::with_capacity(resp.len());

        for position in resp {
            let inst = match self.resolve_report_instrument(
                position.inst_id,
                position.inst_type,
                false,
                true,
                scope,
            )? {
                InstrumentResolution::Found(inst) => inst,
                InstrumentResolution::Skip => continue,
                InstrumentResolution::Incomplete => {
                    anyhow::bail!(
                        "Instrument {} missing from cache for position report",
                        position.inst_id
                    );
                }
            };

            let report = parse_position_status_report(
                &position,
                account_id,
                inst.id(),
                inst.size_precision(),
                ts_init,
            )
            .with_context(|| {
                format!(
                    "failed to parse position status report for instrument {}",
                    position.inst_id
                )

View on GitHub (pinned to 18893faf8b)

Solutions

1. Ensure instruments are loaded into the cache before generating position reports (call the instrument-loading / `load_cache` path for the adapter).
2. Widen the instrument scope/filter so the instrument in `position.inst_id` is included in instrument loading.
3. Verify the `inst_id` from OKX matches a loaded instrument (check for expired/swapped contract IDs in the position).
4. If the instrument is genuinely unavailable, close or manually reconcile the orphaned position instead of relying on automatic reports.

Example fix

// before: reports generated before instruments loaded
adapter.generate_position_status_reports().await?;
// after: load instruments first, then generate
adapter.load_instruments(&fx_cache, &eq_cache).await?;
adapter.generate_position_status_reports().await?;

// ensure instruments are cached before generating reports
for inst_id in position_instrument_ids {
    if !cache.instrument(&inst_id).is_some() {
        anyhow::bail!("pre-flight: instrument {inst_id} not in cache; load instruments first");
    }
}

match adapter.generate_position_status_reports().await {
    Ok(reports) => reports,
    Err(e) if e.to_string().contains("missing from cache for position report") => {
        adapter.load_instruments(&fx, &eq).await?;
        adapter.generate_position_status_reports().await?
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling order/position report generation (e.g. `generate_order_status_reports` / position report flows) while the OKX instrument for `position.inst_id` is absent from the adapter's instrument cache — typically because `load_cache`/instrument loading was never called, or the instrument (e.g. a newly listed or expired contract) was filtered out as out-of-scope.

Common situations: Starting a node with an incomplete cache before all instruments are loaded; positions on delisted or newly listed OKX instruments not in the configured instrument scope; running position reconciliation after a restart where instruments were not re-initialized.

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} missing from cache
• instrument update lock poisoned
• No usable instruments for {instrument_type:?}, cannot initia
• No usable instruments for {instrument_type:?} family {family
• No instruments loaded for configured types {instrument_types

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