pandas-dev/pandas · error · ValueError

freq={freq} is incompatible with unit={unit}. Use a lower fr

Error message

freq={freq} is incompatible with unit={unit}. Use a lower freq or a higher unit instead.

What it means

`ValueError('freq=... is incompatible with unit=...')` from `generate_regular_range`. After converting `freq` to a `Timedelta`, pandas calls `td.as_unit(unit, round_ok=False)`; if the stride is not a whole multiple of `unit` (e.g. a monthly frequency cannot be expressed in seconds), that call raises and pandas rewraps the message with actionable guidance. This is the unit-resolution check for `date_range`/`period_range` internals.

Source

Thrown at pandas/core/arrays/_ranges.py:74

    -------
    ndarray[np.int64]
        Representing the given resolution.
    """
    istart = start._value if start is not None else None
    iend = end._value if end is not None else None
    if isinstance(freq, Day):
        # In contexts without a timezone, a Day offset is unambiguously
        #  interpretable as Timedelta-like.
        td = Timedelta(days=freq.n)
    else:
        freq.nanos  # raises if non-fixed frequency
        td = Timedelta(freq)
    b: int
    e: int
    try:
        td = td.as_unit(unit, round_ok=False)
    except ValueError as err:
        raise ValueError(
            f"freq={freq} is incompatible with unit={unit}. "
            "Use a lower freq or a higher unit instead."
        ) from err
    stride = int(td._value)

    if periods is None and istart is not None and iend is not None:
        b = istart
        # cannot just use e = Timestamp(end) + 1 because arange breaks when
        # stride is too large, see GH10887
        e = b + (iend - b) // stride * stride + stride // 2 + 1
    elif istart is not None and periods is not None:
        b = istart
        e = _generate_range_overflow_safe(b, periods, stride, side="start")
    elif iend is not None and periods is not None:
        e = iend + stride
        b = _generate_range_overflow_safe(e, periods, stride, side="end")
    else:
        raise ValueError(

View on GitHub (pinned to 3b7651241d)

Solutions

  1. Use a lower freq (smaller stride) that divides the unit, e.g. switch from `'M'` to `'D'` or `'h'`.
  2. Use a higher (finer) unit: `unit='ns'` always works because strides are integer nanos.
  3. Switch to a fixed-frequency offset that `freq.nanos` accepts (e.g. `'h'`, `'min'`) before specifying `unit`.

Example fix

// before
pd.date_range('2020-01-01', periods=3, freq='M', unit='s')
# -> freq=M is incompatible with unit=s

// after
pd.date_range('2020-01-01', periods=3, freq='M')            # default ns
# or
pd.date_range('2020-01-01', periods=3, freq='h', unit='s')
Defensive patterns

Strategy: validation

Validate before calling

from pandas import Timedelta
try:
    Timedelta(freq).as_unit(unit, round_ok=False)
except ValueError:
    unit = 'ns'   # or pick a finer unit / smaller freq
pd.date_range(start, periods=N, freq=freq, unit=unit)

Type guard

def freq_unit_compatible(freq, unit) -> bool:
    from pandas import Timedelta
    try:
        Timedelta(freq).as_unit(unit, round_ok=False)
        return True
    except ValueError:
        return False

Try / catch

try:
    rng = pd.date_range(start, periods=N, freq=freq, unit=unit)
except ValueError as e:
    if 'is incompatible with unit' in str(e):
        rng = pd.date_range(start, periods=N, freq=freq)   # default ns
    else:
        raise

Prevention

When it happens

Trigger: Calling `pd.date_range(start, end, freq=<non-fixed or sub-unit offset>, unit='s'|'ms'|'us'|'ns')` where the offset's nanosecond stride is not divisible by the unit. Example: `freq='M'` (month begin) with `unit='s'`; `freq='W'` with a unit smaller than a week if the stride is non-integer in that unit.

Common situations: Using a higher (coarser) `unit=` than the frequency allows; passing a non-fixed calendar offset (MonthEnd, YearBegin) which has no fixed nanos representation combined with a non-ns unit; unit introduced in pandas 2.x without considering freq compatibility.

Related errors

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