pandas-dev/pandas · error · OutOfBoundsTimedelta

Overflow in timedelta division

Error message

Overflow in timedelta division

What it means

Raised by TimedeltaArray._check_float_div_overflow when dividing a timedelta64 array by a float whose quotient would exceed int64 nanosecond range. numpy's timedelta/float division silently saturates past int64 bounds, so pandas computes the float64 quotient (ignoring NaT/zero/NaN) and raises OutOfBoundsTimedelta if any active quotient reaches 2**63. The routine first tries an extreme-element fast path before falling back to the per-element check.

Solutions

1. Increase the float divisor so quotients stay within ±2**63 ns.
2. Convert to coarser units (e.g. total_seconds) before the division so the effective quotient fits int64.
3. Clip the source timedelta values before dividing.

Example fix

# before
pd.to_timedelta(10**17, unit='ns') / 1e-6  # OutOfBoundsTimedelta

# after
(pd.to_timedelta(10**17, unit='ns').total_seconds()) / 1e-6

import numpy as np

def td_float_div_is_safe(td_ns_values, divisor):
    a = np.asarray(td_ns_values, dtype='i8')
    d = np.asarray(divisor, dtype='f8')
    a_safe = np.where(a == np.int64(np.iinfo(np.int64).min), 0, a)
    with np.errstate(divide='ignore', invalid='ignore'):
        q = a_safe / d
    mask = np.isnan(q) | (d == 0)
    return np.max(np.abs(q), initial=0.0, where=~mask) < 2**63

null

from pandas.errors import OutOfBoundsTimedelta
try:
    result = td / divisor
except OutOfBoundsTimedelta:
    result = td.dt.total_seconds() / divisor

When it happens

Trigger: `pd.to_timedelta(10**17, unit='ns') / 1e-6`, or dividing a large-duration Series by a tiny float divisor.

Common situations: Normalizing durations by very small float factors; unit conversions that expand ns magnitudes; aggregations producing tiny divisors.

Related errors

• Cannot convert input with unit
• Overflow in int64 multiplication
• Overflow in timedelta multiplication
• Cannot divide by
• Cannot divide vectors with unequal lengths

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/f1c515789a6be0c1. Report an issue: GitHub.

Appendix: source

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

        other_arr = np.asarray(other)
        if other_arr.ndim == 0 and i8.size:
            divisor = other_arr.item()
            if divisor == 0 or np.isnan(divisor):
                # numpy returns all-NaT; nothing to check
                return
            # The extreme elements bound all quotients, so most cases resolve
            #  without the full per-element check below. A NaT (int64.min)
            #  dividend can only false-trip this bound, never pass an
            #  overflowing quotient.
            low_quot = i8.min() / divisor
            high_quot = i8.max() / divisor
            if max(abs(low_quot), abs(high_quot)) < 2.0**63:
                return
        with np.errstate(divide="ignore", invalid="ignore"):
            f_quot = i8 / other_arr
        exclude_mask = (i8 == iNaT) | np.isnan(f_quot) | (other_arr == 0)
        if np.max(np.abs(f_quot), initial=0.0, where=~exclude_mask) >= 2.0**63:
            raise OutOfBoundsTimedelta("Overflow in timedelta division")

    def _scalar_divlike_op(self, other, op):
        """
        Shared logic for __truediv__, __rtruediv__, __floordiv__, __rfloordiv__
        with scalar 'other'.
        """
        if isinstance(other, self._recognized_scalars):
            other = Timedelta(other)
            # mypy assumes that __new__ returns an instance of the class
            # github.com/python/mypy/issues/1020
            if cast("Timedelta | NaTType", other) is NaT:
                # specifically timedelta64-NaT
                res = np.empty(self.shape, dtype=np.float64)
                res.fill(np.nan)
                return res

            # otherwise, dispatch to Timedelta implementation
            return op(self._ndarray, other)

View on GitHub (pinned to 3b7651241d)