python/cpython · error · OverflowError

result out of range

Error message

result out of range

What it means

Raised by date.__add__ when adding a timedelta to a date produces an ordinal day number outside the representable range (1 to date.max.toordinal(), _MAXORDINAL). Python dates span 0001-01-01 to 9999-12-31, and arithmetic that crosses either boundary raises OverflowError instead of wrapping. Note __sub__ with a timedelta delegates to __add__ with the negated timedelta, so it can raise the same error.

Source

Thrown at Lib/_pydatetime.py:1234

        y, m, d = self._year, self._month, self._day
        y2, m2, d2 = other._year, other._month, other._day
        return _cmp((y, m, d), (y2, m2, d2))

    def __hash__(self):
        "Hash."
        if self._hashcode == -1:
            self._hashcode = hash(self._getstate())
        return self._hashcode

    # Computations

    def __add__(self, other):
        "Add a date to a timedelta."
        if isinstance(other, timedelta):
            o = self.toordinal() + other.days
            if 0 < o <= _MAXORDINAL:
                return type(self).fromordinal(o)
            raise OverflowError("result out of range")
        return NotImplemented

    __radd__ = __add__

    def __sub__(self, other):
        """Subtract two dates, or a date and a timedelta."""
        if isinstance(other, timedelta):
            return self + timedelta(-other.days)
        if isinstance(other, date):
            days1 = self.toordinal()
            days2 = other.toordinal()
            return timedelta(days1 - days2)
        return NotImplemented

    def weekday(self):
        "Return day of the week, where Monday == 0 ... Sunday == 6."
        return (self.toordinal() + 6) % 7

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Clamp inputs before arithmetic: verify date.min <= d + td <= date.max before applying
2. Bound the loop or offset so the running date stays within date.min..date.max
3. Catch OverflowError at the call site and handle the boundary case explicitly (e.g. cap at date.max)

Example fix

// before
new_date = d + timedelta(days=offset)  # OverflowError near boundaries

// after
new_date = d + timedelta(days=offset) if date.min <= d + timedelta(days=offset) <= date.max else None
if new_date is None:
    new_date = date.max if offset > 0 else date.min

from datetime import date, timedelta

def safe_add(d: date, td: timedelta) -> date:
    lo = d.toordinal() + td.days
    if 1 <= lo <= date.max.toordinal():
        return d + td
    raise OverflowError(f'{d} + {td} leaves representable range')

try:
    new_d = d + td
except OverflowError:
    new_d = date.max if td.days > 0 else date.min  # explicit clamp policy

When it happens

Trigger: date.min - timedelta(days=1); date.max + timedelta(days=1); date(1,1,1) + timedelta(days=-365*3000); date(9999,12,31) + timedelta(weeks=2); any accumulated loop of date += timedelta that eventually steps past date.max.

Common situations: Date arithmetic over long horizons (interest calculation to year 9999+), unbounded while-loops that increment a date, subtracting large timedeltas from early dates, or business logic projecting far-future expiry dates.

Related errors

• timedelta # of days is too large: %d
• Unknown timespec value
• Invalid ISO string
• Invalid isoformat string
• Inconsistent use of dash separator

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