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 DatetimeArray.to_period when no `freq` is passed and the index has no inferable frequency (self._inferred_freq_str is None). Conversion to PeriodArray requires a period frequency; if the DatetimeIndex is irregular (gaps, duplicates, unordered), pandas cannot guess one.

Solutions

1. Pass an explicit freq: `dti.to_period('D')`, `dti.to_period('M')`, etc.
2. Re-establish a regular index first: `df.asfreq('D')` or `df.resample('D').asfreq()` before to_period.
3. Drop duplicates and sort: `dti = dti.drop_duplicates().sort_values()` then retry.
4. If you only want period-like grouping, use `.dt.to_period('M')` on a column rather than the index.

Example fix

// before
periods = irregular_dti.to_period()

// after
periods = irregular_dti.to_period('D')

import pandas as pd

def safe_to_period(dti, freq=None):
    freq = freq or dti.freq
    if freq is None:
        freq = 'D'
    return dti.to_period(freq=freq)

def has_inferable_freq(dti) -> bool:
    return dti.freq is not None or dti.inferred_freq is not None

try:
    p = dti.to_period()
except ValueError as e:
    if 'freq argument' in str(e):
        p = dti.to_period('D')
    else:
        raise

When it happens

Trigger: Calling `dti.to_period()` on an irregular DatetimeIndex (filtered, resampled-but-not-asfreq, manually constructed, or containing duplicates/NaT). Calling `.to_period()` on a Series.dt accessor whose underlying index is irregular.

Common situations: Filtering rows then `.to_period('M')` works (freq explicit) but `.to_period()` without an arg fails because the filtered index lost its regular cadence. Reading real-world timestamps that have jitter or missing rows.

Related errors

• cannot add Period to a
• Cannot add and
• cannot subtract from
• cannot subtract from
• mean is not implemented for

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

Appendix: source

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

        >>> 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 3b7651241d)