nautechsystems/nautilus_trader · error

seconds timestamp should be within valid range

Error message

seconds timestamp should be within valid range

What it means

After converting epoch seconds to i64, the generator passes them to jiff's Timestamp::from_second, which panics here when the value is outside jiff's supported range (roughly years -9999..9999). A valid i64 second count far beyond that range (or negative pre-epoch values from a broken clock) triggers the panic.

Source

Thrown at crates/common/src/generators/client_order_id.rs:60

            + "-".len()
    } else {
        "O".len() + DATETIME_TAG_COMPACT_LEN + trader_tag.len() + strategy_tag.len()
    }
}

/// Slow path across second boundaries: rebuilds the fixed prefix directly in the output buffer.
fn write_fixed_prefix(
    buf: &mut String,
    trader_tag: &str,
    strategy_tag: &str,
    use_hyphens: bool,
    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();

    if use_hyphens {
        write!(
            buf,
            "O-{: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");
    } else {
        write!(

View on GitHub (pinned to 18893faf8b)

Solutions

1. Sanity-check the epoch second (e.g. within a plausible window around now) before formatting
2. Fix the clock or mock supplying the extreme timestamp
3. Use a checked fallback: Timestamp::from_second(sec).unwrap_or(Timestamp::NOW) if a degraded ID prefix is acceptable
4. For tests, restrict generated timestamps to jiff's supported range

Example fix

// before
Timestamp::from_second(
    i64::try_from(epoch_second).expect("seconds timestamp should fit i64"),
)
.expect("seconds timestamp should be within valid range")
// after
let ts = Timestamp::from_second(sec)
    .unwrap_or(Timestamp::NOW);

fn within_jiff_range(sec: u64) -> bool {
    let s = i64::try_from(sec).unwrap_or(i64::MAX);
    (-377_705_023_201..=253_402_300_799).contains(&s)
}

// Use a checked conversion with fallback
let ts = Timestamp::from_second(sec as i64)
    .unwrap_or(Timestamp::NOW);

When it happens

Trigger: Calling write_fixed_prefix (via refresh_fixed_prefix) with an epoch_second whose i64 conversion succeeds but whose value lies outside Timestamp::from_second's supported range (e.g. i64::MAX seconds, or a u64-wrapped/negative-corrupted clock value).

Common situations: Broken system clocks; mocks/fuzz tests with extreme timestamps; corrupted u64 time sources overflowing after conversion.

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 fit i64
• Event '{}' should have associated handler
• UnixNanos overflow in from_seconds
• UnixNanos overflow in from_millis
• UnixNanos overflow in from_micros

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