nautechsystems/nautilus_trader · error

seconds timestamp should be within valid range

Error message

seconds timestamp should be within valid range

What it means

This panic comes from `Timestamp::from_second(...).expect("seconds timestamp should be within valid range")` in `write_fixed_prefix` in crates/common/src/generators/order_list_id.rs. The epoch value fit in i64 but jiff only accepts timestamps within roughly -9999..9999 years (i64 seconds in range -377705023201..253402300799), so an out-of-range i64 second value is rejected and the expect panics.

Source

Thrown at crates/common/src/generators/order_list_id.rs:148

}

#[inline]
fn fixed_prefix_capacity(trader_tag: &str, strategy_tag: &str) -> usize {
    "OL-".len()
        + DATETIME_TAG_LEN
        + "-".len()
        + trader_tag.len()
        + "-".len()
        + strategy_tag.len()
        + "-".len()
}

fn write_fixed_prefix(buf: &mut String, trader_tag: &str, strategy_tag: &str, epoch_second: u64) {
    let now_utc = Offset::UTC.to_datetime(
        Timestamp::from_second(
            i64::try_from(epoch_second).expect("seconds timestamp should fit i64"),
        )
        .expect("seconds timestamp should be within valid range"),
    );

    buf.clear();

    write!(
        buf,
        "OL-{:04}{:02}{:02}-{:02}{:02}{:02}-{trader_tag}-{strategy_tag}-",
        now_utc.year(),
        now_utc.month(),
        now_utc.day(),
        now_utc.hour(),
        now_utc.minute(),
        now_utc.second(),
    )
    .expect("writing to String should not fail");
}

#[cfg(test)]

View on GitHub (pinned to 18893faf8b)

Solutions

1. Validate the epoch seconds are within jiff's supported range before calling: `-377705023201 <= secs <= 253402300799`
2. Fix the clock source to return real current Unix seconds
3. In tests, use a fixed realistic timestamp fixture rather than i64 extremes

Example fix

// before
let secs: i64 = i64::MAX; // out of jiff range
generator.refresh_fixed_prefix(u64::try_from(secs).unwrap());
// after
const MIN_SECS: i64 = -377705023201;
const MAX_SECS: i64 = 253402300799;
assert!((MIN_SECS..=MAX_SECS).contains(&secs), "epoch seconds out of representable range");
generator.refresh_fixed_prefix(u64::try_from(secs).unwrap());

fn in_jiff_range(secs: i64) -> bool { (-377705023201..=253402300799).contains(&secs) }

When it happens

Trigger: Calling `refresh_fixed_prefix` with an epoch_second that converts to an i64 outside jiff's valid timestamp range — e.g. values beyond year 9999 or before year -9999 (negative seconds below -377705023201, or above 253402300799).

Common situations: Mock clocks or generated test values using i64::MAX/MIN, bad deserialization of timestamps, or clock misconfiguration producing absurd epoch values passed into the OrderListId generator.

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

• seconds timestamp should be within valid range
• UnixNanos overflow in from_seconds
• UnixNanos overflow in from_millis
• UnixNanos overflow in from_micros
• seconds timestamp should fit i64

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