nautechsystems/nautilus_trader · error · anyhow::Error

on_symbol_mapping failed for

Error message

on_symbol_mapping failed for {msg:?}: {e}

What it means

When the live feed delivers a `dbn::SymbolMappingMsg`, the feed handler applies it to a point-in-time `PitSymbolMap` via `on_symbol_mapping`. If that mapping update fails, the error is wrapped with the offending message and this text. A failure here means symbol-mapping state (Databento raw symbol to instrument ID) can no longer be trusted for that channel, so decoding subsequent records for that instrument may be wrong.

Solutions

  1. Inspect the logged `msg` to see the exact SymbolMappingMsg that was rejected
  2. Check the databento crate version matches the server dataset/schema expectations (upgrade if needed)
  3. Verify the stype_in/stype_out combination used at subscribe time is consistent
  4. Clear/reset the symbol map state (restart the session) so the PitSymbolMap is rebuilt cleanly
  5. If persistent, report/reproduce with Databento support — the mapping record may be genuinely malformed

Example fix

// before
symbol_map.on_symbol_mapping(msg)?;

// after
symbol_map
    .on_symbol_mapping(msg)
    .map_err(|e| {
        log::warn!("skipping bad symbol mapping: {e}");
        anyhow::anyhow!("on_symbol_mapping failed for {msg:?}: {e}")
    })?;
Defensive patterns

Strategy: try-catch

Validate before calling

// pin and verify databento crate version against dataset expectations
cargo tree -p databento | grep databento

Try / catch

match feed_result {
    Err(e) if e.to_string().contains("on_symbol_mapping failed") => {
        log::error!("symbol mapping failure: {e:#}");
        // rebuild symbol map / restart session with consistent stype
    }
    other => other?,
}

Prevention

When it happens

Trigger: A symbol mapping record arrives whose content the `PitSymbolMap` rejects — e.g. a mapping inconsistent with previously seen mappings, malformed mapping data in the Databento stream, or a pit-map invariant violation while processing the `SymbolMappingMsg`.

Common situations: Databento schema/symbology changes producing unexpected mapping records; subscribing with stype combinations that yield conflicting mappings; corrupted or out-of-order stream data after reconnects; version drift between the databento crate and server record formats.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

        .strip_circumfix("Subscription request ", " data succeeded")
        .and_then(|rest| rest.split_once(" for "))
        .map(|(_, schema)| schema.trim().to_string())
        .unwrap_or_default()
}

/// Handles symbol mapping messages and updates the instrument ID map.
///
/// # Errors
///
/// Returns an error if symbol mapping fails.
fn handle_symbol_mapping_msg(
    msg: &dbn::SymbolMappingMsg,
    symbol_map: &mut PitSymbolMap,
    instrument_id_map: &mut AHashMap<u32, InstrumentId>,
) -> anyhow::Result<()> {
    symbol_map
        .on_symbol_mapping(msg)
        .map_err(|e| anyhow::anyhow!("on_symbol_mapping failed for {msg:?}: {e}"))?;
    instrument_id_map.remove(&msg.header().instrument_id);
    Ok(())
}

fn update_price_precision_map_with_symbol_mapping_msg(
    msg: &dbn::SymbolMappingMsg,
    price_precision_overrides: &AHashMap<Symbol, u8>,
    subscription_price_precision_map: &mut AHashMap<u32, u8>,
) -> anyhow::Result<()> {
    subscription_price_precision_map.remove(&msg.hd.instrument_id);

    if price_precision_overrides.is_empty() {
        return Ok(());
    }

    let stype_in_symbol = msg
        .stype_in_symbol()
        .map_err(|e| anyhow::anyhow!("Error decoding `stype_in_symbol`: {e}"))?;

View on GitHub (pinned to 18893faf8b)