nautechsystems/nautilus_trader · error · anyhow::Error

Binance timestamp is outside the UnixNanos range

Error message

Binance {field} timestamp is outside the UnixNanos range: {value}

What it means

parse_timestamp converts an i64 epoch value into UnixNanos; when the conversion result is None because the value (a non-negative, typically very large millisecond/microsecond value) exceeds what UnixNanos can represent, this 'outside the UnixNanos range' error is raised.

Solutions

1. Verify you are passing the correct field and unit (millis vs micros) from the Binance response.
2. Sanity-check the raw value is a plausible epoch time before parsing.
3. Fix corrupted upstream data or fixtures containing huge values.
4. Use parse_millis_or_init if a fallback ts_init is acceptable for invalid values.

Example fix

// before
let ts = parse_micros(i64::MAX, "time")?;

// after
let ts = parse_millis(raw_time, "time")?; // correct unit and real field value

fn is_plausible_ts(v: i64) -> bool { v >= 0 && v < 4_102_444_800_000 } // millis bound
// micros: use parse_micros only for genuinely microsecond fields

When it happens

Trigger: Calling parse_millis or parse_micros with an i64 so large that converting to UnixNanos (nanosecond precision) overflows — e.g. microsecond timestamps far in the future, garbage values, or misread fields where a non-timestamp number is passed as a timestamp.

Common situations: Passing microseconds where milliseconds are expected (or vice versa) is usually safe, but absurd/future values from corrupted data or sentinel values like i64::MAX trigger this; unit tests using arbitrary large numbers.

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

• invalid negative Binance
• invalid negative kline trade count
• microsecond timestamp
• millisecond timestamp
• second timestamp overflows when scaled to nanoseconds

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

Appendix: source

Thrown at crates/adapters/binance/src/common/parse.rs:92

pub(crate) fn parse_millis(value: i64, field: &str) -> anyhow::Result<UnixNanos> {
    parse_timestamp(value, UnixNanos::from_millis_checked(value), field)
}

pub(crate) fn parse_micros(value: i64, field: &str) -> anyhow::Result<UnixNanos> {
    parse_timestamp(value, UnixNanos::from_micros_checked(value), field)
}

fn parse_timestamp(
    value: i64,
    timestamp: Option<UnixNanos>,
    field: &str,
) -> anyhow::Result<UnixNanos> {
    timestamp.ok_or_else(|| {
        if value < 0 {
            anyhow::anyhow!("invalid negative Binance {field} timestamp: {value}")
        } else {
            anyhow::anyhow!("Binance {field} timestamp is outside the UnixNanos range: {value}")
        }
    })
}

pub(crate) fn parse_millis_or_init(value: i64, field: &str, ts_init: UnixNanos) -> UnixNanos {
    timestamp_or_init(parse_millis(value, field), ts_init)
}

pub(crate) fn parse_micros_or_init(value: i64, field: &str, ts_init: UnixNanos) -> UnixNanos {
    timestamp_or_init(parse_micros(value, field), ts_init)
}

fn timestamp_or_init(timestamp: anyhow::Result<UnixNanos>, ts_init: UnixNanos) -> UnixNanos {
    match timestamp {
        Ok(timestamp) => timestamp,
        Err(e) => {
            log::warn!("{e}; using initialization timestamp");
            ts_init

View on GitHub (pinned to 18893faf8b)