python/cpython · error · OverflowError

timedelta # of days is too large: %d

Error message

timedelta # of days is too large: %d

What it means

Raised by timedelta.__new__ after normalization when the absolute day count |d| exceeds 999999999. timedelta's internal representation bounds days to ±999999999 (about ±2.7 million years); any combination of components (including weeks*7 or multiplication later via __mul__) that normalizes beyond that raises OverflowError.

Source

Thrown at Lib/_pydatetime.py:751

            s += seconds
            microseconds = round(microseconds + usdouble)
        assert isinstance(s, int)
        assert isinstance(microseconds, int)
        assert abs(s) <= 3 * 24 * 3600
        assert abs(microseconds) < 3.1e6

        # Just a little bit of carrying possible for microseconds and seconds.
        seconds, us = divmod(microseconds, 1000000)
        s += seconds
        days, s = divmod(s, 24*3600)
        d += days

        assert isinstance(d, int)
        assert isinstance(s, int) and 0 <= s < 24*3600
        assert isinstance(us, int) and 0 <= us < 1000000

        if abs(d) > 999999999:
            raise OverflowError("timedelta # of days is too large: %d" % d)

        self = object.__new__(cls)
        self._days = d
        self._seconds = s
        self._microseconds = us
        self._hashcode = -1
        return self

    def __repr__(self):
        args = []
        if self._days:
            args.append("days=%d" % self._days)
        if self._seconds:
            args.append("seconds=%d" % self._seconds)
        if self._microseconds:
            args.append("microseconds=%d" % self._microseconds)
        if not args:
            args.append('0')

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Check the magnitude before constructing: keep |days| <= 999999999
2. Catch OverflowError when multiplying or exponentiating timedeltas
3. Switch to relative-date arithmetic on date objects within 1..9999 instead of giant timedeltas

Example fix

// before
d = timedelta(microseconds=1) * 10**17  # OverflowError
// after
try:
    d = timedelta(microseconds=1) * factor
except OverflowError:
    d = timedelta.max  # or handle out-of-range explicitly

if abs(total_days) > 999_999_999:
    raise OverflowError('duration out of representable range')

try:
    d = base_delta * factor
except OverflowError:
    d = timedelta.max  # or clamp / report
else:
    use(d)

When it happens

Trigger: timedelta(days=10**9); timedelta(weeks=10**9); timedelta(hours=1) * 10**9; accumulating timedeltas in a loop that multiplies a large factor.

Common situations: Multiplying durations by huge counts (e.g. timedelta(seconds=1) * ns_per_century); unit errors passing microseconds where days expected; computing date.max + big delta via timedelta arithmetic.

Related errors

• unsupported type for timedelta {name} component: {type(value
• result out of range
• cannot mix naive and timezone-aware time
• Unknown timespec value
• Invalid ISO string

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/d1e5d14b561e020c. Report an issue: GitHub.