nautechsystems/nautilus_trader · error

Wrong schema ID: expected

Error message

Wrong schema ID: expected {crate::spot::sbe::spot::SBE_SCHEMA_ID}, received {schema_id}

What it means

decode_execution_report checks the SBE header's schema ID against the crate's expected spot SBE schema ID. This error means the payload was encoded with a different schema version/definition than the codecs compiled into this adapter, so field layouts may be incompatible. The decoder refuses to interpret bytes it cannot safely map.

Solutions

  1. Update the adapter's generated SBE codecs to the schema version Binance currently serves
  2. Re-encode or re-capture test fixtures with the schema version matching SBE_SCHEMA_ID
  3. Confirm the payload comes from the Binance Spot SBE user-data stream, not another schema
  4. Log the received schema ID and compare with the expected constant to identify the version drift

Example fix

// before
let report = decode_execution_report(old_captured_frame)?;
// after
let schema_id = u16::from_be_bytes([old_captured_frame[4], old_captured_frame[5]]);
anyhow::ensure!(schema_id == crate::spot::sbe::spot::SBE_SCHEMA_ID, "re-capture fixture with current schema");
let report = decode_execution_report(old_captured_frame)?;
Defensive patterns

Strategy: validation

Validate before calling

pub fn has_expected_schema(data: &[u8]) -> bool {
    data.len() >= 8
        && u16::from_be_bytes([data[4], data[5]]) == crate::spot::sbe::spot::SBE_SCHEMA_ID
}

Type guard

fn with_current_schema(data: &[u8]) -> Option<&[u8]> {
    (data.len() >= 8
        && u16::from_be_bytes([data[4], data[5]]) == crate::spot::sbe::spot::SBE_SCHEMA_ID)
    .then_some(data)
}

Try / catch

match decode_execution_report(&frame) {
    Ok(r) => handle(r),
    Err(e) if e.to_string().contains("Wrong schema ID") => {
        alert_schema_drain(&frame); // capture for codec regeneration
    }
    Err(e) => log::warn!("SBE decode failed: {e}"),
}

Prevention

When it happens

Trigger: Calling decode_execution_report with a frame whose header bytes 4-5 hold a schema ID differing from crate::spot::sbe::spot::SBE_SCHEMA_ID — e.g. a payload captured from an older/newer Binance SBE schema, or a test fixture built with mismatched schema constants.

Common situations: Binance publishing a new SBE schema revision while the adapter ships stale generated codecs; mixing captured binary fixtures from different schema eras in tests; proxying streams from another venue/product that uses a different schema ID.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — 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/526010055231653a. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/binance/src/spot/websocket/trading/decode_sbe.rs:84

            data.len()
        );
    }

    let buf = ReadBuf::new(data);
    let block_length = buf.get_u16_at(0);
    let template_id = buf.get_u16_at(2);
    let schema_id = buf.get_u16_at(4);
    let version = buf.get_u16_at(6);

    if template_id != execution_report_event_codec::SBE_TEMPLATE_ID {
        anyhow::bail!(
            "Wrong template ID: expected {}, received {template_id}",
            execution_report_event_codec::SBE_TEMPLATE_ID
        );
    }

    if schema_id != crate::spot::sbe::spot::SBE_SCHEMA_ID {
        anyhow::bail!(
            "Wrong schema ID: expected {}, received {schema_id}",
            crate::spot::sbe::spot::SBE_SCHEMA_ID
        );
    }

    let min_block_len = execution_report_min_block_length(version);
    if usize::from(block_length) < min_block_len {
        anyhow::bail!(
            "SBE execution report block length too short: expected at least {min_block_len}, was {block_length}"
        );
    }

    let min_len = HEADER_LEN + usize::from(block_length);
    if data.len() < min_len {
        anyhow::bail!(
            "Buffer too short for fixed block: expected {min_len}, was {}",
            data.len()
        );

View on GitHub (pinned to 18893faf8b)