{"record":{"id":"55e746802e142b34","repo":"pandas-dev/pandas","slug":"freq-freq-is-incompatible-with-unit-unit-use","errorCode":null,"errorMessage":"freq={freq} is incompatible with unit={unit}. Use a lower freq or a higher unit instead.","messagePattern":"freq=(.+?) is incompatible with unit=(.+?)\\. Use a lower freq or a higher unit instead\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/_ranges.py","lineNumber":74,"sourceCode":"    -------\n    ndarray[np.int64]\n        Representing the given resolution.\n    \"\"\"\n    istart = start._value if start is not None else None\n    iend = end._value if end is not None else None\n    if isinstance(freq, Day):\n        # In contexts without a timezone, a Day offset is unambiguously\n        #  interpretable as Timedelta-like.\n        td = Timedelta(days=freq.n)\n    else:\n        freq.nanos  # raises if non-fixed frequency\n        td = Timedelta(freq)\n    b: int\n    e: int\n    try:\n        td = td.as_unit(unit, round_ok=False)\n    except ValueError as err:\n        raise ValueError(\n            f\"freq={freq} is incompatible with unit={unit}. \"\n            \"Use a lower freq or a higher unit instead.\"\n        ) from err\n    stride = int(td._value)\n\n    if periods is None and istart is not None and iend is not None:\n        b = istart\n        # cannot just use e = Timestamp(end) + 1 because arange breaks when\n        # stride is too large, see GH10887\n        e = b + (iend - b) // stride * stride + stride // 2 + 1\n    elif istart is not None and periods is not None:\n        b = istart\n        e = _generate_range_overflow_safe(b, periods, stride, side=\"start\")\n    elif iend is not None and periods is not None:\n        e = iend + stride\n        b = _generate_range_overflow_safe(e, periods, stride, side=\"end\")\n    else:\n        raise ValueError(","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/_ranges.py#L56-L92","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a lower freq (smaller stride) that divides the unit, e.g. switch from `'M'` to `'D'` or `'h'`.","Use a higher (finer) unit: `unit='ns'` always works because strides are integer nanos.","Switch to a fixed-frequency offset that `freq.nanos` accepts (e.g. `'h'`, `'min'`) before specifying `unit`."],"exampleFix":"// before\npd.date_range('2020-01-01', periods=3, freq='M', unit='s')\n# -> freq=M is incompatible with unit=s\n\n// after\npd.date_range('2020-01-01', periods=3, freq='M')            # default ns\n# or\npd.date_range('2020-01-01', periods=3, freq='h', unit='s')","handlingStrategy":"validation","validationCode":"from pandas import Timedelta\ntry:\n    Timedelta(freq).as_unit(unit, round_ok=False)\nexcept ValueError:\n    unit = 'ns'   # or pick a finer unit / smaller freq\npd.date_range(start, periods=N, freq=freq, unit=unit)","typeGuard":"def freq_unit_compatible(freq, unit) -> bool:\n    from pandas import Timedelta\n    try:\n        Timedelta(freq).as_unit(unit, round_ok=False)\n        return True\n    except ValueError:\n        return False","tryCatchPattern":"try:\n    rng = pd.date_range(start, periods=N, freq=freq, unit=unit)\nexcept ValueError as e:\n    if 'is incompatible with unit' in str(e):\n        rng = pd.date_range(start, periods=N, freq=freq)   # default ns\n    else:\n        raise","preventionTips":["Default to unit='ns' when unsure","Prefer fixed-frequency offsets when specifying a non-ns unit"],"tags":["date-range","freq","unit","resolution"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}