nautechsystems/nautilus_trader · error

Invalid `ImbalanceMsg`

Error message

Invalid `ImbalanceMsg`

What it means

`read_imbalance_records` requires each record to decode as `dbn::ImbalanceMsg`; if `record.get::<ImbalanceMsg>()` yields None the loader returns this error. It signals the input stream does not actually contain imbalance records.

Source

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

                        &record,
                        instrument_id,
                        &mut metadata_cache,
                    ) {
                        Ok(id) => id,
                        Err(e) => return Some(Err(e)),
                    };
                    let resolved_precision = match self.resolve_stream_price_precision(
                        &instrument_id,
                        fixed_instrument_id,
                        &mut fixed_price_precision,
                    ) {
                        Ok(p) => p,
                        Err(e) => return Some(Err(e)),
                    };

                    let msg = match record.get::<dbn::ImbalanceMsg>() {
                        Some(m) => m,
                        None => return Some(Err(anyhow::anyhow!("Invalid `ImbalanceMsg`"))),
                    };
                    let ts_init = msg.ts_recv.into();

                    match decode_imbalance_msg(
                        msg,
                        instrument_id,
                        resolved_precision,
                        Some(ts_init),
                    ) {
                        Ok(data) => Some(Ok(data)),
                        Err(e) => Some(Err(e)),
                    }
                }
                None => None,
            }
        }))
    }

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Re-download the data with `schema="imbalance"`
  2. Point `read_imbalance_records` at the correct file containing imbalance records
  3. Split mixed-schema files per schema before loading
  4. Verify rtype in the DBN header before loading
Defensive patterns

Strategy: validation

Validate before calling

assert_eq!(request.schema, "imbalance", "read_imbalance_records requires the imbalance schema");

Type guard

fn is_imbalance_record(rec: &dbn::RecordRef) -> bool {
    rec.get::<dbn::ImbalanceMsg>().is_some()
}

Try / catch

match loader.read_imbalance_records(file, instrument_id, price_precision).next() {
    Some(Ok(_)) => { /* proceed */ }
    Some(Err(e)) if e.to_string().contains("Invalid `ImbalanceMsg`") => {
        anyhow::bail!("not an imbalance stream; re-download with schema=imbalance");
    }
    other => { /* handle normally */ }
}

Prevention

When it happens

Trigger: Calling `read_imbalance_records` on a DBN stream whose rtype/schema is not imbalance (e.g. quotes or trades), typically because the download used the wrong `schema` parameter.

Common situations: Confusing Databento's `imbalance` schema with standard quote data, or feeding a mixed-schema stream to the imbalance reader.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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