nautechsystems/nautilus_trader · error

missing metadata cache for dynamic instrument id

Error message

missing metadata cache for dynamic instrument id

What it means

Databento's DBN decoder can map some record instrument IDs directly, but dynamic (numeric) instrument IDs require a metadata cache holding the symbology (symbol maps) to be resolved to a Nautilus InstrumentId. This error is thrown in resolve_record_instrument_id when a dynamic instrument ID is encountered but the caller passed a None metadata cache. It is a defensive invariant: loading data with dynamic IDs without metadata is impossible to resolve.

Source

Thrown at crates/adapters/databento/src/loader.rs:960

                    Err(e) => return Some(Err(e)),
                }
            }
        }))
    }

    fn resolve_record_instrument_id(
        &self,
        record: &dbn::RecordRef,
        instrument_id: Option<InstrumentId>,
        metadata_cache: &mut Option<MetadataCache>,
    ) -> anyhow::Result<InstrumentId> {
        if let Some(instrument_id) = instrument_id {
            return Ok(instrument_id);
        }

        let metadata_cache = metadata_cache
            .as_mut()
            .ok_or_else(|| anyhow::anyhow!("missing metadata cache for dynamic instrument id"))?;

        decode_nautilus_instrument_id(
            record,
            metadata_cache,
            &self.publisher_venue_map,
            &self.symbol_venue_map,
        )
    }

    fn resolve_stream_price_precision(
        &self,
        instrument_id: &InstrumentId,
        fixed_instrument_id: bool,
        fixed_price_precision: &mut Option<u8>,
    ) -> anyhow::Result<u8> {
        if let Some(precision) = *fixed_price_precision {
            return Ok(precision);
        }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Pass a metadata cache to the loader: obtain `databento::Metadata` from the historical client (get_range/get_batch call) and attach it via the loader's metadata_cache setter before reading.
2. Request data for explicit symbols so records resolve to non-dynamic instrument IDs and the cache is not needed.
3. If reading pre-downloaded DBN files, load the matching metadata file first and register it with the loader.
4. Verify the dataset does not use dynamic instrument IDs for the record types you decode (GLBX.MDP3 definitions/status typically do).

Example fix

// before
loader.read_order_book_deltas(&mut handler, None)?;

// after
let metadata = client.get_range(...).await?.metadata;
loader.set_metadata_cache(metadata);
loader.read_order_book_deltas(&mut handler, None)?;

// Rust
anyhow::ensure!(
    loader.metadata_cache().is_some(),
    "metadata cache required for datasets with dynamic instrument ids"
);

match loader.read_order_book_deltas(&mut handler, None) {
    Ok(_) => {},
    Err(e) if e.to_string().contains("missing metadata cache") => attach_metadata_and_retry(loader)?,
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling read_records / read_order_book_deltas / load_status_records / read_imbalance_records / read_statistics_records on a dataset whose records use dynamic instrument IDs (e.g. GLBX.MDP3 raw numeric IDs) while passing None for metadata_cache, typically when the loader was not built with symbology metadata (no `databento::Metadata` from the batch/download call).

Common situations: Reading historical data files without their accompanying metadata; constructing a DatabentoDataLoader manually and skipping set_metadata_cache; streaming records from a source that does not provide DBN metadata; requesting data where instrument_id was not fixed via the `symbols` parameter so records carry dynamic IDs.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• No raw symbol found for {instrument_id}
• Invalid `{SCHEMA_PARAM}` '{schema}'. Must be one of: {allowe
• Invalid negative `contract_multiplier`: {value}
• `rtype` is not a supported bar aggregation, was {msg.hd.rtyp
• Invalid `MboMsg` parsing combination

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