pandas-dev/pandas · error · TypeError

Not supported to convert PeriodArray to '{type}' type

Error message

Not supported to convert PeriodArray to '{type}' type

What it means

Raised by PeriodArray.__arrow_array__ when the target pyarrow type is neither an integer type nor an ArrowPeriodType. PeriodArray can only export losslessly to pyarrow int64 (raw ordinals + mask) or to a matching ArrowPeriodType; any other pyarrow type (string, timestamp, float) is unsupported via this path.

Source

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

        """
        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",
        """
        The year of the period.

        Returns the year component for each period in the index.

        See Also

View on GitHub (pinned to 71959b8cb9)

Solutions

  1. Omit the explicit type: pa.__arrow_array__() returns a pyarrow.ExtensionArray of ArrowPeriodType.
  2. For timestamps, convert first: pa.to_timestamp().__arrow_array__(type=pyarrow.timestamp('us')).
  3. For raw ordinals, target pyarrow.int64().

Example fix

# before
import pyarrow as pa
arr = pd.period_array(['2020-01-01'], dtype=pd.PeriodDtype('D')).__arrow_array__(type=pa.string())
# after
arr = pd.period_array(['2020-01-01'], dtype=pd.PeriodDtype('D')).__arrow_array__()  # ArrowPeriodType
# or convert to timestamp first
ts = pd.period_array(['2020-01-01'], dtype=pd.PeriodDtype('D')).to_timestamp()
arr = ts.__arrow_array__(type=pa.timestamp('us'))
Defensive patterns

Strategy: validation

Validate before calling

import pyarrow as pa
from pandas.core.arrays.arrow.extension_types import ArrowPeriodType

def supported_arrow_type(t):
    if t is None or pa.types.is_integer(t) or isinstance(t, ArrowPeriodType):
        return True
    return False

Type guard

import pyarrow as pa
from pandas.core.arrays.arrow.extension_types import ArrowPeriodType

def arrow_type_supports_period(t) -> bool:
    return t is None or pa.types.is_integer(t) or isinstance(t, ArrowPeriodType)

Try / catch

try:
    out = period_array.__arrow_array__(type=target)
except TypeError:
    out = period_array.__arrow_array__()

Prevention

When it happens

Trigger: pa.__arrow_array__(type=pyarrow.string()), pa.__arrow_array__(type=pyarrow.timestamp('ns')), or pyarrow.array(pa, type=some_unsupported_type).

Common situations: Hardcoded Arrow schemas that assume period maps to timestamp or string. Migrating legacy parquet schemas. Generic to_arrow helpers that pass through whatever type the user specified.

Related errors

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