pandas-dev/pandas · error · ValueError

Period dtypes are not supported, use a PeriodIndex instead

Error message

Period dtypes are not supported, use a PeriodIndex instead

What it means

Raised as a ValueError when one side of the interval is a PeriodIndex. Periods represent fixed-frequency spans themselves, so nesting them inside an IntervalArray is ambiguous; pandas directs you to PeriodIndex instead. Fires at pandas/core/arrays/interval.py:337.

Source

Thrown at pandas/core/arrays/interval.py:337

            msg = (
                f"must not have differing left [{type(left).__name__}] and "
                f"right [{type(right).__name__}] types"
            )
            raise ValueError(msg)
        if (
            isinstance(left.dtype, CategoricalDtype)
            or is_string_dtype(left.dtype)
            or is_string_dtype(right.dtype)
        ):
            # GH 19016, GH 66518: reject unsupported right-side dtypes too.
            msg = (
                "category, object, and string subtypes are not supported "
                "for IntervalArray"
            )
            raise TypeError(msg)
        if isinstance(left, ABCPeriodIndex):
            msg = "Period dtypes are not supported, use a PeriodIndex instead"
            raise ValueError(msg)
        if isinstance(left, ABCDatetimeIndex) and str(left.tz) != str(right.tz):
            msg = (
                "left and right must have the same time zone, got "
                f"'{left.tz}' and '{right.tz}'"
            )
            raise ValueError(msg)
        elif needs_i8_conversion(left.dtype) and left.unit != right.unit:
            # e.g. m8[s] vs m8[ms], try to cast to a common dtype GH#55714
            left_arr, right_arr = left._data._ensure_matching_resos(right._data)
            left = ensure_index(left_arr)
            right = ensure_index(right_arr)

        # For dt64/td64 we want DatetimeArray/TimedeltaArray instead of ndarray
        left = ensure_wrapped_if_datetimelike(left)
        left = extract_array(left, extract_numpy=True)
        right = ensure_wrapped_if_datetimelike(right)
        right = extract_array(right, extract_numpy=True)

View on GitHub (pinned to 71959b8cb9)

Solutions

Use a `pd.PeriodIndex` directly to represent period spans.
If you need true intervals, convert periods to timestamps: `left.to_timestamp()`, `right.to_timestamp(how='end')`.

Example fix

// before
pd.IntervalIndex.from_arrays(per_left, per_right)
// after
pd.PeriodIndex(per_left.to_timestamp(), freq='Q')  # or
pd.IntervalIndex.from_arrays(per_left.to_timestamp(), per_right.to_timestamp(how='end'))

Defensive patterns

Strategy: type-guard

Validate before calling

import pandas as pd

def build_from_periods(left, right):
    if isinstance(left, pd.PeriodIndex) or isinstance(right, pd.PeriodIndex):
        left = left.to_timestamp() if isinstance(left, pd.PeriodIndex) else left
        right = right.to_timestamp(how='end') if isinstance(right, pd.PeriodIndex) else right
    return pd.IntervalArray(left, right)

Type guard

import pandas as pd

def is_period_index(arr) -> bool:
    return isinstance(arr, pd.PeriodIndex)

Try / catch

try:
    ia = pd.IntervalArray(left, right)
except ValueError as e:
    if "Period dtypes are not supported" in str(e):
        ia = pd.IntervalArray(left.to_timestamp(), right.to_timestamp(how='end'))
    else:
        raise

Prevention

Detect PeriodIndex inputs upstream and convert to timestamps.
Document that interval bounds must be numeric/datetime/timedelta.
Add an integration test with period inputs to lock in the conversion.

When it happens

Trigger: `pd.IntervalIndex.from_arrays(period_idx_a, period_idx_b)` where both inputs are `pd.PeriodIndex`, or passing a `PeriodDtype` as the interval subtype.

Common situations: Trying to build ranges over period data (e.g., 'from Q1 to Q3') by treating two PeriodIndex arrays as bounds.

Related errors

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