{"record":{"id":"a5be5bba2881968e","repo":"pandas-dev/pandas","slug":"specified-freq-and-dtype-are-different","errorCode":null,"errorMessage":"specified freq and dtype are different","messagePattern":"specified freq and dtype are different","errorType":"exception","errorClass":"IncompatibleFrequency","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/period.py","lineNumber":1455,"sourceCode":"    ----------\n    dtype : dtype\n    dtype2 : PeriodDtype or None\n        Dtype derived from a `freq` passed to the caller.\n\n    Returns\n    -------\n    PeriodDtype or None\n\n    Raises\n    ------\n    ValueError : non-period dtype\n    IncompatibleFrequency : mismatch between dtype and freq\n    \"\"\"\n    if dtype is not None:\n        if not isinstance(dtype, PeriodDtype):\n            raise ValueError(\"dtype must be PeriodDtype\")\n        if dtype2 is not None and dtype != dtype2:\n            raise IncompatibleFrequency(\"specified freq and dtype are different\")\n\n    elif dtype2 is not None:\n        if not isinstance(dtype2, PeriodDtype):\n            raise ValueError(\"dtype must be PeriodDtype\")\n        dtype = dtype2\n\n    return dtype\n\n\ndef dt64arr_to_periodarr(\n    data, freq, tz=None\n) -> tuple[npt.NDArray[np.int64], BaseOffset]:\n    \"\"\"\n    Convert a datetime-like array to values Period ordinals.\n\n    Parameters\n    ----------\n    data : Union[Series[datetime64[ns]], DatetimeIndex, ndarray[datetime64ns]]","sourceCodeStart":1437,"sourceCodeEnd":1473,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/period.py#L1437-L1473","documentation":"Raised by validate_dtype_freq as pandas.errors.IncompatibleFrequency when both an explicit dtype (PeriodDtype) and a freq-derived dtype2 are supplied but they disagree. Pandas refuses to silently pick one frequency over the other because that would change period semantics.","triggerScenarios":"Calling period_range/PeriodIndex/PeriodArray with freq='D' and dtype=pd.PeriodDtype('M'); constructing PeriodIndex from existing Period objects of one frequency while passing freq= of another; converting between Period dtypes via construction instead of .asfreq().","commonSituations":"Refactoring code that changed the freq literal but left a stale dtype kwarg; building from a Series of Period('2020', 'A') values while passing freq='Q'; user input plumbing both freq and dtype independently.","solutions":["Pick one source of truth: pass only freq or only dtype=pd.PeriodDtype(freq), not both.","If conversion is intended, use PeriodIndex.asfreq(target_freq) on the existing index instead of re-constructing.","Reconcile the two literals so freq matches the dtype's freq."],"exampleFix":"# before\npd.period_range('2020', periods=3, freq='D', dtype=pd.PeriodDtype('M'))\n# after\npd.period_range('2020', periods=3, freq='D')\n# or convert explicitly\npd.period_range('2020', periods=3, freq='M').asfreq('D')","handlingStrategy":"validation","validationCode":"from pandas import PeriodDtype\n\ndef reconcile(freq, dtype):\n    if freq is not None and dtype is not None:\n        derived = PeriodDtype(freq) if isinstance(freq, str) else PeriodDtype(freq.freqstr)\n        if derived != dtype:\n            raise ValueError(f'freq {freq!r} disagrees with dtype {dtype!r}')\n    return dtype","typeGuard":"def freq_matches_dtype(freq, dtype) -> bool:\n    if dtype is None or freq is None:\n        return True\n    return pd.PeriodDtype(freq) == dtype","tryCatchPattern":"from pandas.errors import IncompatibleFrequency\ntry:\n    pi = pd.period_range(start, periods=n, freq=freq, dtype=dtype)\nexcept IncompatibleFrequency:\n    pi = pd.period_range(start, periods=n, freq=freq)  # drop dtype","preventionTips":["Pass only one of freq= or dtype= to period constructors.","Use PeriodIndex.asfreq() for frequency conversion instead of reconstruction.","Add a unit test that asserts your helper never sets both kwargs."],"tags":["pandas","period","freq","incompatible"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}