pandas-dev/pandas · error · OutOfBoundsTimedelta

{err.args}

Error message

{err.args}

What it means

Re-raise site inside sequence_to_td64ns: when converting float data through cast_from_unit_vectorized raises OutOfBoundsDatetime (values out of int64 range after unit scaling), pandas re-raises it as OutOfBoundsTimedelta, preserving the original message via err.args. This is a conversion-overflow guard for to_timedelta on floats with a unit.

Source

Thrown at pandas/core/arrays/timedeltas.py:1294

            # check pass incorrectly for OOB values like float(2**63).
            # Exclude values outside the int64 domain from the check.
            i64 = np.iinfo(np.int64)
            in_int64_range = (data >= np.float64(i64.min)) & (
                data < np.float64(i64.max)
            )
            all_round = (mask | (in_int64_range & (data == int_data))).all()
            if all_round:
                result = sequence_to_td64ns(
                    int_data, copy=False, unit=unit, errors=errors
                )
                result[mask] = iNaT
                return result

        data = data.astype(np.float64, copy=False)
        try:
            data = cast_from_unit_vectorized(data, unit or "ns")
        except OutOfBoundsDatetime as err:
            raise OutOfBoundsTimedelta(*err.args) from err
        data[mask] = iNaT
        data = data.view("m8[ns]")
        copy = False

    elif lib.is_np_dtype(data.dtype, "m"):
        if not is_supported_dtype(data.dtype):
            # cast to closest supported unit, i.e. s or ns
            new_dtype = get_supported_dtype(data.dtype)
            data = astype_overflowsafe(data, dtype=new_dtype, copy=False)
            copy = False

    else:
        # This includes datetime64-dtype, see GH#23539, GH#29794
        raise TypeError(f"dtype {data.dtype} cannot be converted to timedelta64[ns]")

    if not copy:
        data = np.asarray(data)
    else:

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Reduce magnitude: clip or scale the floats before conversion.
2. Use a coarser target by converting in steps (e.g. seconds first, then to_timedelta).
3. Pass errors='coerce' to surface NaT instead of raising.

Example fix

// before
s = pd.to_timedelta([1e20], unit='s')

// after
s = pd.to_timedelta([1e20], unit='s', errors='coerce')

import numpy as np
arr = np.asarray(data, dtype='float64')
projected = arr * {'s': 10**9, 'ms': 10**6, 'us': 10**3, 'ns': 1}.get(unit, 1)
if np.nanmax(np.abs(projected)) >= 2.0**63:
    raise ValueError('float values overflow timedelta64[ns] after unit scaling')

try:
    s = pd.to_timedelta(data, unit=unit)
except OutOfBoundsTimedelta:
    s = pd.to_timedelta(data, unit=unit, errors='coerce')

When it happens

Trigger: Calling pd.to_timedelta on float values with a unit that pushes them out of int64-nanosecond range, e.g. `pd.to_timedelta([1e20], unit='s')`. NaT-handling branch sets mask but the unmasked conversion overflows.

Common situations: Loading telemetry with huge epoch offsets; specifying a coarse unit ('D','W') on already-large floats; unit-mismatch bugs.

Related errors

• Cannot convert input with unit '{unit}'
• overflow in timedelta operation
• Overflow in timedelta multiplication
• Overflow in int64 multiplication
• Overflow in timedelta division

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/753eecf578dc53a9. Report an issue: GitHub.