pandas-dev/pandas · error · IncompatibleFrequency

Cannot add/subtract timedelta-like from PeriodArray that is

Error message

Cannot add/subtract timedelta-like from PeriodArray that is not an integer multiple of the PeriodArray's freq.

What it means

Raised by PeriodArray._add_timedelta_arraylike when astype_overflowsafe cannot losslessly convert the timedelta to the period's tick unit with round_ok=False. Example: a minutes-freq period array plus 30 seconds — 30s is not a whole number of minutes — so there is no valid ordinal delta.

Source

Thrown at pandas/core/arrays/period.py:1273

        """
        if not self.dtype._is_tick_like():
            # We cannot add timedelta-like to non-tick PeriodArray
            raise TypeError(
                f"Cannot add or subtract timedelta64[ns] dtype from {self.dtype}"
            )

        dtype = np.dtype(f"m8[{self.dtype._td64_unit}]")

        # Similar to _check_timedeltalike_freq_compat, but we raise with a
        #  more specific exception message if necessary.
        try:
            delta = astype_overflowsafe(
                np.asarray(other), dtype=dtype, copy=False, round_ok=False
            )
        except ValueError as err:
            # e.g. if we have minutes freq and try to add 30s
            # "Cannot losslessly convert units"
            raise IncompatibleFrequency(
                "Cannot add/subtract timedelta-like from PeriodArray that is "
                "not an integer multiple of the PeriodArray's freq."
            ) from err

        res_values = add_overflowsafe(self.asi8, np.asarray(delta.view("i8")))
        return type(self)(res_values, dtype=self.dtype)

    def _check_timedeltalike_freq_compat(self, other):
        """
        Arithmetic operations with timedelta-like scalars or array `other`
        are only valid if `other` is an integer multiple of `self.freq`.
        If the operation is valid, find that integer multiple.  Otherwise,
        raise because the operation is invalid.

        Parameters
        ----------
        other : timedelta, np.timedelta64, Tick,
                ndarray[timedelta64], TimedeltaArray, TimedeltaIndex

View on GitHub (pinned to 71959b8cb9)

Solutions

Round the timedelta to a whole multiple of the freq: Timedelta(seconds=60).
Choose a finer freq: pa.asfreq('s') + Timedelta(seconds=30).
Shift by integer periods: pa + n where n is the count of freq steps.

Example fix

# before
pa = pd.period_range('2020-01-01 00:00','2020-01-01 02:00', freq='min')._data
pa + pd.Timedelta(seconds=30)
# after
pa + pd.Timedelta(minutes=1)
# or finer freq
pa.asfreq('s') + pd.Timedelta(seconds=30)

Defensive patterns

Strategy: validation

Validate before calling

import pandas as pd

def timedelta_is_multiple_of(td: pd.Timedelta, freq: str) -> bool:
    base = pd.Timedelta(1, unit={'min':'min','h':'h','s':'s','D':'D','us':'us','ns':'ns'}.get(freq, 's'))
    return td % base == pd.Timedelta(0)

Type guard

import pandas as pd

def is_whole_multiple(td, pa) -> bool:
    unit = pa.dtype._td64_unit
    base = pd.Timedelta(1, unit=unit)
    return td % base == pd.Timedelta(0)

Try / catch

from pandas.errors import IncompatibleFrequency
try:
    out = pa + td
except IncompatibleFrequency:
    out = pa.asfreq('s') + td

Prevention

Snap timedeltas to whole multiples of the period freq.
Choose a freq at least as fine as the smallest offset you add.
Catch IncompatibleFrequency and degrade to a finer freq.

When it happens

Trigger: period_range(freq='min') + pd.Timedelta(seconds=30); period freq='h' plus 90 minutes works (1.5h fails only if not a multiple); mismatched sub-tick timedeltas.

Common situations: Sensor data with second-level offsets on minute-period columns. Timezone/DST math producing non-integer offsets. User input mixing units (hours + seconds) naively.

Related errors

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