pandas-dev/pandas · error · TypeError

Not supported to convert PeriodArray to array with different

Error message

Not supported to convert PeriodArray to array with different 'freq' ({self.freqstr} vs {type.freq})

What it means

Raised by PeriodArray.__arrow_array__ when the target pyarrow type is an ArrowPeriodType whose freq string differs from the array's freq. Period data is frequency-tagged, so exporting to a pyarrow period extension type with a mismatched freq would silently relabel the ordinals; pandas refuses.

Source

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

        # This will raise TypeError for non-object dtypes
        return np.array(list(self), dtype=object)

    def __arrow_array__(self, type=None):
        """
        Convert myself into a pyarrow Array.
        """
        import pyarrow

        from pandas.core.arrays.arrow.extension_types import ArrowPeriodType

        if type is not None:
            if pyarrow.types.is_integer(type):
                return pyarrow.array(self._ndarray, mask=self.isna(), type=type)
            elif isinstance(type, ArrowPeriodType):
                # ensure we have the same freq
                if self.freqstr != type.freq:
                    raise TypeError(
                        "Not supported to convert PeriodArray to array with different "
                        f"'freq' ({self.freqstr} vs {type.freq})"
                    )
            else:
                raise TypeError(
                    f"Not supported to convert PeriodArray to '{type}' type"
                )

        period_type = ArrowPeriodType(self.freqstr)
        storage_array = pyarrow.array(self._ndarray, mask=self.isna(), type="int64")
        return pyarrow.ExtensionArray.from_storage(period_type, storage_array)

    # --------------------------------------------------------------------
    # Vectorized analogues of Period properties

    year = _field_accessor(
        "year",
        """

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Align the target schema freq to the data: use ArrowPeriodType(pa.freqstr).
2. Convert the array's freq first: pa.asfreq('M') then export.
3. Drop the explicit type and let __arrow_array__ infer the matching ArrowPeriodType.

Example fix

# before
import pyarrow as pa_par
from pandas.core.arrays.arrow.extension_types import ArrowPeriodType
pa = pd.period_array(['2020-01-01'], dtype=pd.PeriodDtype('D'))
storage = pa.__arrow_array__(type=ArrowPeriodType('M'))
# after
storage = pa.__arrow_array__(type=ArrowPeriodType(pa.freqstr))
# or convert freq first
storage = pa.asfreq('M').__arrow_array__(type=ArrowPeriodType('M'))

from pandas.core.arrays.arrow.extension_types import ArrowPeriodType

def arrow_period_type_for(pa):
    return ArrowPeriodType(pa.freqstr)

def freq_matches(pa, arrow_type) -> bool:
    return getattr(arrow_type, 'freq', None) == pa.freqstr

try:
    out = pa.__arrow_array__(type=target_type)
except TypeError:
    out = pa.__arrow_array__()  # let pandas infer the matching type

When it happens

Trigger: pa.__arrow_array__(type=ArrowPeriodType('M')) on a period[D] array. pd.array(...).to_arrow() with an explicit schema carrying a different period freq. pyarrow.Table.from_pandas with a schema mismatch.

Common situations: Schema evolution where the stored freq changed. Joining DataFrames whose period columns were declared with different freqs. Arrow-based ETL pipelines with hardcoded period schemas.

Related errors

• Not supported to convert PeriodArray to '{type}' type
• dtype is not specified and cannot be inferred
• Unable to avoid copy while creating an array as requested.
• Cannot add or subtract timedelta64[ns] dtype from {self.dtyp
• Cannot add/subtract timedelta-like from PeriodArray that is

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