pola-rs/polars · error

out-of-range duration

Error message

out-of-range duration

What it means

`duration_s_to_duration` converts an i64 seconds value into a chrono `Duration` via `Duration::try_seconds`. When the value exceeds what chrono's Duration can represent (out of ±i64-millisecond-ish span, roughly ±292 years), `try_seconds` returns `None` and `.expect("out-of-range duration")` panics.

Solutions

1. Check the value against chrono's Duration limits before conversion, or use `chrono::Duration::try_seconds(v)` directly and handle `None`.
2. Replace sentinel/garbage values in the column before conversion.
3. Confirm the unit is actually seconds, not ms/us/ns, which would scale the value out of range.

Example fix

// before
let d = duration_s_to_duration(v); // panics on i64::MAX
// after
let d = chrono::Duration::try_seconds(v)
    .ok_or_else(|| anyhow!("duration seconds {v} out of range"))?;

fn duration_s_in_range(v: i64) -> bool {
    chrono::Duration::try_seconds(v).is_some()
}

match chrono::Duration::try_seconds(v) {
    Some(d) => /* use d */,
    None => /* handle out-of-range duration */,
}

When it happens

Trigger: Calling `duration_s_to_duration(v)` with |v| beyond chrono Duration's representable range (about ±9.2e15 seconds is safe; near i64::MAX seconds overflows).

Common situations: Sentinel values (i64::MAX) in duration(s) columns; unit confusion treating a nanosecond field as seconds; extreme test data.

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

• out-of-range in duration conversion
• invalid or out-of-range datetime
• out-of-range date
• invalid time
• Invalid time unit ' ' for Duration.

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/af035c4dc21f80c3. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-arrow/src/temporal_conversions.rs:79

        .expect("invalid or out-of-range datetime")
}

/// converts a `i64` representing a `date64` to [`NaiveDate`]
#[inline]
pub fn date64_to_date(milliseconds: i64) -> NaiveDate {
    date64_to_datetime(milliseconds).date()
}

/// converts a `i32` representing a `time32(s)` to [`NaiveTime`]
#[inline]
pub fn time32s_to_time(v: i32) -> NaiveTime {
    NaiveTime::from_num_seconds_from_midnight_opt(v as u32, 0).expect("invalid time")
}

/// converts a `i64` representing a `duration(s)` to [`Duration`]
#[inline]
pub fn duration_s_to_duration(v: i64) -> Duration {
    Duration::try_seconds(v).expect("out-of-range duration")
}

/// converts a `i64` representing a `duration(ms)` to [`Duration`]
#[inline]
pub fn duration_ms_to_duration(v: i64) -> Duration {
    Duration::try_milliseconds(v).expect("out-of-range in duration conversion")
}

/// converts a `i64` representing a `duration(us)` to [`Duration`]
#[inline]
pub fn duration_us_to_duration(v: i64) -> Duration {
    Duration::microseconds(v)
}

/// converts a `i64` representing a `duration(ns)` to [`Duration`]
#[inline]
pub fn duration_ns_to_duration(v: i64) -> Duration {
    Duration::nanoseconds(v)

View on GitHub (pinned to fe841f959e)