pandas-dev/pandas · error · TypeError

Passing PeriodDtype data is invalid. Use…

Error message

Passing PeriodDtype data is invalid. Use `data.to_timestamp()` instead

What it means

Raised by maybe_convert_dtype when the input data has a PeriodDtype. Period objects are a distinct temporal type (a time span anchored to a frequency) and cannot be reinterpreted as datetime64[ns] instants without an explicit conversion choice. The message points to the supported API: PeriodIndex.to_timestamp().

Solutions

Convert explicitly with the recommended API: `period_obj.to_timestamp()` (or `.dt.to_timestamp()` on a Series).
Pass `freq` if you want a specific anchor: `period_index.to_timestamp(freq='D')`.
If you wanted the period end: `period_index.to_timestamp(how='end')`.
Re-check whether the destination really wants datetime64 — if downstream accepts Period, pass the Period through unchanged.

Example fix

// before
dti = pd.DatetimeIndex(period_index)

// after
dti = period_index.to_timestamp()

Defensive patterns

Strategy: type-guard

Validate before calling

import pandas as pd

def period_to_datetime(obj):
    if isinstance(getattr(obj, 'dtype', None), pd.PeriodDtype):
        return obj.dt.to_timestamp()
    return obj

Type guard

def is_period(obj) -> bool:
    import pandas as pd
    return isinstance(getattr(obj, 'dtype', None), pd.PeriodDtype)

Try / catch

try:
    dti = pd.DatetimeIndex(period_index)
except TypeError as e:
    if 'PeriodDtype data is invalid' in str(e):
        dti = period_index.to_timestamp()
    else:
        raise

Prevention

Use to_timestamp() to move from Period to datetime — never DatetimeIndex(period_data).
Check dtype with isinstance(..., pd.PeriodDtype) before datetime conversion.

When it happens

Trigger: Passing a Series with dtype `period[D]` or a PeriodIndex into `pd.DatetimeIndex(...)`, `pd.to_datetime(period_series)`, or any datetime constructor that routes through maybe_convert_dtype. Assigning a Period column into a datetime-typed slot.

Common situations: Switching modeling granularity from periods to timestamps (e.g. monthly periods -> month-start timestamps). Storing periods then handing them to a library that expects datetimes. Bug where the wrong column is referenced.

Related errors

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

Appendix: source

Thrown at pandas/core/arrays/datetimes.py:2905

    if not hasattr(data, "dtype"):
        # e.g. collections.deque
        return data, copy

    if is_float_dtype(data.dtype):
        # pre-2.0 we treated these as wall-times, inconsistent with ints
        # GH#23675, GH#45573 deprecated to treat symmetrically with integer dtypes.
        # Note: data.astype(np.int64) fails ARM tests, see
        # https://github.com/pandas-dev/pandas/issues/49468.
        data = data.astype(DT64NS_DTYPE).view("i8")
        copy = False

    elif lib.is_np_dtype(data.dtype, "m") or is_bool_dtype(data.dtype):
        # GH#29794 enforcing deprecation introduced in GH#23539
        raise TypeError(f"dtype {data.dtype} cannot be converted to datetime64[ns]")
    elif isinstance(data.dtype, PeriodDtype):
        # Note: without explicitly raising here, PeriodIndex
        #  test_setops.test_join_does_not_recur fails
        raise TypeError(
            "Passing PeriodDtype data is invalid. Use `data.to_timestamp()` instead"
        )

    elif isinstance(data.dtype, ExtensionDtype) and not isinstance(
        data.dtype, DatetimeTZDtype
    ):
        # TODO: We have no tests for these
        data = np.array(data, dtype=np.object_)
        copy = False

    return data, copy


# -------------------------------------------------------------------
# Validation and Inference


def _maybe_infer_tz(tz: tzinfo | None, inferred_tz: tzinfo | None) -> tzinfo | None:

View on GitHub (pinned to 3b7651241d)