What causes "specified freq and dtype are different" in pandas-dev/pandas?

Drop one: pass either freq or dtype, not contradictory both.

pandas-dev/pandas · error · IncompatibleFrequency

specified freq and dtype are different

Error message

specified freq and dtype are different

What it means

Raised by validate_dtype_freq when both an explicit dtype and an inferred freq-derived dtype2 are supplied but they are not equal. The constructor refuses to silently pick one over the other; the caller must reconcile them.

Source

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

    ----------
    dtype : dtype
    dtype2 : PeriodDtype or None
        Dtype derived from a `freq` passed to the caller.

    Returns
    -------
    PeriodDtype or None

    Raises
    ------
    ValueError : non-period dtype
    IncompatibleFrequency : mismatch between dtype and freq
    """
    if dtype is not None:
        if not isinstance(dtype, PeriodDtype):
            raise ValueError("dtype must be PeriodDtype")
        if dtype2 is not None and dtype != dtype2:
            raise IncompatibleFrequency("specified freq and dtype are different")

    elif dtype2 is not None:
        if not isinstance(dtype2, PeriodDtype):
            raise ValueError("dtype must be PeriodDtype")
        dtype = dtype2

    return dtype


def dt64arr_to_periodarr(
    data, freq, tz=None
) -> tuple[npt.NDArray[np.int64], BaseOffset]:
    """
    Convert a datetime-like array to values Period ordinals.

    Parameters
    ----------
    data : Union[Series[datetime64[ns]], DatetimeIndex, ndarray[datetime64ns]]

View on GitHub (pinned to 71959b8cb9)

Solutions

Drop one: pass either freq or dtype, not contradictory both.
Align them: dtype=PeriodDtype(freq) computed from the same freq value.
Validate equality before calling: if dtype != PeriodDtype(freq): raise.

Example fix

# before
validate_dtype_freq(pd.PeriodDtype('M'), pd.PeriodDtype('D'))
# after
freq = 'D'
validate_dtype_freq(pd.PeriodDtype(freq), pd.PeriodDtype(freq))
# or just
validate_dtype_freq(None, pd.PeriodDtype('D'))

Defensive patterns

Strategy: validation

Validate before calling

from pandas.core.dtypes.dtypes import PeriodDtype

def reconcile(dtype, freq):
    if dtype is not None and freq is not None and dtype != PeriodDtype(freq):
        raise ValueError(f'dtype {dtype} conflicts with freq {freq}')
    return dtype or (PeriodDtype(freq) if freq else None)

Type guard

from pandas.core.dtypes.dtypes import PeriodDtype

def dtype_freq_consistent(dtype, freq) -> bool:
    return dtype is None or freq is None or dtype == PeriodDtype(freq)

Try / catch

from pandas.errors import IncompatibleFrequency
try:
    dt = validate_dtype_freq(dtype, dtype2)
except IncompatibleFrequency:
    dt = validate_dtype_freq(None, dtype2)

Prevention

Pass only one of freq/dtype to period constructors.
Derive dtype from freq programmatically to avoid drift.
Assert consistency at config-load time.

When it happens

Trigger: Calling a period constructor with freq='D' and dtype=PeriodDtype('M') simultaneously. APIs that accept both freq and dtype and let the user contradict themselves.

Common situations: Config files where freq and dtype come from different sources. Refactors that pass through both args without deduping. Copy-paste from examples with mismatched units.

Related errors

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