pandas-dev/pandas · error · ValueError

You must pass a freq argument as current index has none.

Error message

You must pass a freq argument as current index has none.

What it means

Raised by DatetimeIndex.to_period when neither an explicit freq nor an inferrable freq exists on the index. to_period needs a frequency to map each timestamp to a Period; without one the mapping is undefined. ValueError.

Source

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

        >>> idx.to_period()
        PeriodIndex(['2017-01-01', '2017-01-02'],
                    dtype='period[D]')
        """
        from pandas.core.arrays import PeriodArray

        if self.tz is not None:
            warnings.warn(
                "Converting to PeriodArray/Index representation "
                "will drop timezone information.",
                UserWarning,
                stacklevel=find_stack_level(),
            )

        if freq is None:
            freq = self._inferred_freq_str

            if freq is None:
                raise ValueError(
                    "You must pass a freq argument as current index has none."
                )

            res = get_period_alias(freq)

            #  https://github.com/pandas-dev/pandas/issues/33358
            if res is None:
                res = freq

            freq = res
        return PeriodArray._from_datetime64(self._ndarray, freq, tz=self.tz)

    # -----------------------------------------------------------------
    # Properties - Vectorized Timestamp Properties/Methods

    def month_name(self, locale=None) -> npt.NDArray[np.object_]:
        """
        Return the month names with specified locale.

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Pass an explicit freq: idx.to_period('D') or .to_period(freq='h').
2. If the index should be regular, rebuild it with pd.date_range(..., freq=...) or set a freq via idx.asfreq / idx.inferred_freq.
3. For irregular data, group with .resample('D') or .dt.to_period('D') on the column instead of the index.

Example fix

# before
idx.to_period()
# after
idx.to_period('D')

def safe_to_period(idx, freq=None):
    freq = freq or idx.freq or idx.inferred_freq
    if freq is None:
        raise ValueError('index has no freq; pass freq= explicitly')
    return idx.to_period(freq)

def has_freq(idx) -> bool:
    return getattr(idx, 'freq', None) is not None or idx.inferred_freq is not None

When it happens

Trigger: Calling .to_period() on an irregular DatetimeIndex (timestamps from real events, gaps, duplicates) with no freq= passed; index created from arbitrary datetime lists rather than date_range.

Common situations: Resampling/grouping by period on messy timestamps; converting an event-log index to periods without first ascertaining a freq.

Related errors

• Passing PeriodDtype data is invalid. Use `data.to_timestamp(
• start and end must have same freq
• overflow in timedelta operation
• cannot add Period to a {type(self).__name__}
• Inferred frequency {inferred} from passed values does not co

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