nautechsystems/nautilus_trader · error · anyhow::Error

Cannot resolve `raw_symbol` from `symbol_map` for instrument

Error message

Cannot resolve `raw_symbol` from `symbol_map` for instrument_id {header.instrument_id}

What it means

For any incoming Databento record whose numeric instrument_id is not yet in the cached map, the adapter resolves the raw symbol from the point-in-time symbol map. This error means the map contains no symbol for the record's instrument_id, so a Nautilus InstrumentId cannot be constructed.

Source

Thrown at crates/adapters/databento/src/live.rs:1104

    Ok(instrument_id)
}

fn update_instrument_id_map(
    record: &dbn::RecordRef,
    symbol_map: &PitSymbolMap,
    publisher_venue_map: &IndexMap<PublisherId, Venue>,
    symbol_venue_map: &AtomicMap<Symbol, Venue>,
    instrument_id_map: &mut AHashMap<u32, InstrumentId>,
) -> anyhow::Result<InstrumentId> {
    let header = record.header();

    // Check if instrument ID is already in the map
    if let Some(&instrument_id) = instrument_id_map.get(&header.instrument_id) {
        return Ok(instrument_id);
    }

    let raw_symbol = symbol_map.get_for_rec(record).ok_or_else(|| {
        anyhow::anyhow!(
            "Cannot resolve `raw_symbol` from `symbol_map` for instrument_id {}",
            header.instrument_id
        )
    })?;

    let symbol = Symbol::from_str_unchecked(raw_symbol);

    let publisher_id = header.publisher_id;
    let venue = if let Some(venue) = symbol_venue_map.get_cloned(&symbol) {
        venue
    } else {
        let venue = publisher_venue_map
            .get(&publisher_id)
            .ok_or_else(|| anyhow::anyhow!("No venue found for `publisher_id` {publisher_id}"))?;
        *venue
    };
    let instrument_id = InstrumentId::new(symbol, venue);

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Subscribe to the Databento symbol mapping schema alongside your data schemas so PitSymbolMap is populated
  2. Call load_instruments (definition schema) before streaming other record types
  3. Order your subscriptions so symbol-mapping data arrives before status/statistics/imbalance records
  4. Add a log-and-skip policy for unmapped instrument_ids instead of failing the whole session

Example fix

// before
let raw_symbol = symbol_map.get_for_rec(record).ok_or_else(|| {
    anyhow::anyhow!(
        "Cannot resolve `raw_symbol` from `symbol_map` for instrument_id {}",
        header.instrument_id
    )
})?;
// after
let raw_symbol = match symbol_map.get_for_rec(record) {
    Some(s) => s,
    None => {
        log::warn!("No symbol mapping yet for instrument_id {}", header.instrument_id);
        return Ok(InstrumentId::default());
    }
};
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the symbol map is populated before consuming records
if symbol_map.get_for_rec(&probe_record).is_none() {
    return Err(anyhow::anyhow!("symbol map not initialized; load definitions first"));
}

Try / catch

match update_instrument_id_map(...) {
    Ok(id) => id,
    Err(e) if e.to_string().contains("Cannot resolve `raw_symbol`") => {
        log::warn!("unmapped instrument_id, skipping record");
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: Records (instrument defs, status, imbalance, statistics, or general data) arrive in run_session / handle_record for an instrument_id that has no entry in PitSymbolMap — typically because symbol mapping messages or instrument definitions were not loaded/subscribed before these records.

Common situations: Subscribing to a schema without also subscribing to symbol mappings, missing dataset coverage for an instrument, stream started mid-session where earlier mapping messages were missed.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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