pandas-dev/pandas · error · ValueError

Invalid dtype {dtype} for PeriodArray

Error message

Invalid dtype {dtype} for PeriodArray

What it means

Raised by PeriodArray.__init__ when a dtype argument is supplied but is not a PeriodDtype. PeriodArray only ever carries period[freq] data, so any non-PeriodDtype (int64, datetime64, object, str) passed as dtype is rejected at construction.

Source

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

        "days_in_month",
    ]
    # GH#46768 - deprecated but still need to be accessible via .dt accessor
    _deprecated_ops: list[str] = ["dayofweek", "dayofyear", "daysinmonth"]
    _datetimelike_ops: list[str] = (
        _field_ops + _object_ops + _bool_ops + _deprecated_ops
    )
    _datetimelike_methods: list[str] = ["strftime", "to_timestamp", "asfreq"]

    _dtype: PeriodDtype

    # --------------------------------------------------------------------
    # Constructors

    def __init__(self, values, dtype: Dtype | None = None, copy: bool = False) -> None:
        if dtype is not None:
            dtype = pandas_dtype(dtype)
            if not isinstance(dtype, PeriodDtype):
                raise ValueError(f"Invalid dtype {dtype} for PeriodArray")

        if isinstance(values, ABCSeries):
            values = values._values
            if not isinstance(values, type(self)):
                raise TypeError("Incorrect dtype")

        elif isinstance(values, ABCPeriodIndex):
            values = values._values

        if isinstance(values, type(self)):
            if dtype is not None and dtype != values.dtype:
                raise raise_on_incompatible(values, dtype.freq)
            values, dtype = values._ndarray, values.dtype

        if not copy:
            values = np.asarray(values, dtype="int64")
        else:
            values = np.array(values, dtype="int64", copy=copy)

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Pass a PeriodDtype: dtype=pd.PeriodDtype('D') or dtype='period[D]'.
2. If you only have a freq, let PeriodArray infer from values or pass via period_array(data, dtype=pd.PeriodDtype(freq)).
3. Use the correct array class for the data type (DatetimeArray for timestamps).

Example fix

# before
pd.arrays.PeriodArray([1, 2, 3], dtype='int64')
# after
pd.arrays.PeriodArray(pd.PeriodIndex(['2020-01-01','2020-01-02'], freq='D'))
# or with explicit period dtype
pd.period_array(['2020-01-01','2020-01-02'], dtype=pd.PeriodDtype('D'))

import pandas as pd
from pandas.core.dtypes.dtypes import PeriodDtype

def to_period_array(values, dtype=None):
    if dtype is not None and not isinstance(dtype, PeriodDtype):
        dtype = pd.PeriodDtype(dtype) if isinstance(dtype, str) and dtype.startswith('period') else None
    return pd.period_array(values, dtype=dtype)

from pandas.core.dtypes.dtypes import PeriodDtype

def is_period_dtype(dtype) -> bool:
    return isinstance(dtype, PeriodDtype)

try:
    pa = pd.arrays.PeriodArray(values, dtype=dtype)
except ValueError:
    pa = pd.period_array(values, dtype=pd.PeriodDtype('D'))

When it happens

Trigger: Constructing PeriodArray(values, dtype='int64'), PeriodArray(values, dtype='datetime64[ns]'), or passing a Series/Index whose dtype is not period. Internal calls from period_array()/PeriodIndex that propagate a foreign dtype.

Common situations: Confusing PeriodArray with DatetimeArray/TimedeltaArray. Passing dtype='D' (a freq string) instead of PeriodDtype('D'). Building arrays from mixed metadata where dtype was inferred as object.

Related errors

• Incorrect dtype
• dtype is not specified and cannot be inferred
• PeriodArray does not allow floating point in construction
• Period dtypes are not supported, use a PeriodIndex instead
• Not enough parameters to construct Period range

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