nautechsystems/nautilus_trader · error

Timestamp overflow for record

Error message

Timestamp overflow for record

What it means

get_nautilus_instrument_id_for_record converts the record's nanosecond timestamp into an OffsetDateTime to look up the symbology map for that date. If the nanosecond value overflows the representable range when added to the Unix epoch (checked_add returns None), the timestamp cannot be converted and this error is raised instead of panicking.

Source

Thrown at crates/adapters/databento/src/symbology.rs:145

        (msg.hd.instrument_id, msg.ts_recv)
    } else if let Some(msg) = record.get::<dbn::StatMsg>() {
        (msg.hd.instrument_id, msg.ts_recv)
    } else if let Some(msg) = record.get::<dbn::InstrumentDefMsg>() {
        (msg.hd.instrument_id, msg.ts_recv)
    } else if let Some(msg) = record.get::<dbn::Cmbp1Msg>() {
        (msg.hd.instrument_id, msg.ts_recv)
    } else if let Some(msg) = record.get::<dbn::CbboMsg>() {
        (msg.hd.instrument_id, msg.ts_recv)
    } else if let Some(msg) = record.get::<dbn::TbboMsg>() {
        (msg.hd.instrument_id, msg.ts_recv)
    } else {
        anyhow::bail!("DBN message type is not currently supported")
    };

    let duration = time::Duration::nanoseconds(nanoseconds as i64);
    let datetime = time::OffsetDateTime::UNIX_EPOCH
        .checked_add(duration)
        .ok_or_else(|| anyhow::anyhow!("Timestamp overflow for record"))?;
    let date = datetime.date();
    let symbol_map = metadata.symbol_map_for_date(date)?;
    let raw_symbol = symbol_map
        .get(instrument_id)
        .ok_or_else(|| anyhow::anyhow!("No raw symbol found for {instrument_id}"))?;

    let symbol = Symbol::from_str_unchecked(raw_symbol);

    Ok(InstrumentId::new(symbol, venue))
}

#[must_use]
pub fn infer_symbology_type(symbol: &str) -> SType {
    if symbol.ends_with(".FUT") || symbol.ends_with(".OPT") {
        return SType::Parent;
    }

    let parts: Vec<&str> = symbol.split('.').collect();

View on GitHub (pinned to 18893faf8b)

Solutions

1. Inspect the offending record's raw timestamp values (print the record before mapping) and fix or discard records with invalid timestamps.
2. Re-download the data file — the source is most likely corrupt or truncated.
3. Verify you are decoding with the matching DBN schema/version so fields are not misinterpreted.
4. Filter records by a sane ts range before decoding symbology (e.g. reject ts > now + margin or ts < dataset start).

Example fix

// before
for record in records { let id = get_nautilus_instrument_id_for_record(record, ...)?; }

// after
for record in records.filter(|r| r.ts_event() > MIN_SANE_TS && r.ts_event() < MAX_SANE_TS) {
    let id = get_nautilus_instrument_id_for_record(record, ...)?;
}

// Rust
const MAX_NANOS: i64 = 4_102_444_800_000_000_000; // year 2100
anyhow::ensure!(
    nanoseconds > 0 && (nanoseconds as i64) < MAX_NANOS,
    "implausible record timestamp: {nanoseconds}"
);

let id = match get_nautilus_instrument_id_for_record(record, metadata, venue) {
    Ok(id) => id,
    Err(e) if e.to_string().contains("Timestamp overflow") => {
        log::warn!("dropping record with corrupt timestamp");
        return Ok(None);
    }
    Err(e) => return Err(e.into()),
};

When it happens

Trigger: A record carries an absurd ts_event/ts_recv nanosecond value (e.g. 0-sentinel misused, uninitialized memory decoded as a timestamp, or garbage after failed schema inference) that overflows i64::MAX nanoseconds past 1970.

Common situations: Corrupt or truncated DBN files decoded anyway; decoding a file of a different schema where a non-timestamp field is read as the timestamp; hand-rolled or patched record data with wrong epoch units (micros vs nanos shifted).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• millisecond timestamp overflowed
• WETH balance overflow for included transaction {tx_hash} at
• DurationNanos overflow in from_micros
• UnixNanos overflow in from_seconds
• UnixNanos overflow in from_millis

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