pandas-dev/pandas · error · ValueError

The nonexistent argument must be one of 'raise', 'NaT', 'shi

Error message

The nonexistent argument must be one of 'raise', 'NaT', 'shift_forward', 'shift_backward' or a timedelta object

What it means

Raised by tz_localize when the nonexistent argument is not one of the allowed handling strategies. nonexistent controls what happens to wall-times that fall inside a DST forward gap (e.g. 02:00-03:00 skipped). Anything outside the allowed set or a timedelta is rejected. ValueError.

Source

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

        0   2015-03-29 03:00:00+02:00
        1   2015-03-29 03:30:00+02:00
        dtype: datetime64[ns, Europe/Warsaw]

        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_backward')
        0   2015-03-29 01:59:59.999999999+01:00
        1   2015-03-29 03:30:00.000000000+02:00
        dtype: datetime64[ns, Europe/Warsaw]

        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('1h'))
        0   2015-03-29 03:30:00+02:00
        1   2015-03-29 03:30:00+02:00
        dtype: datetime64[ns, Europe/Warsaw]
        """  # noqa: E501
        nonexistent_options = ("raise", "NaT", "shift_forward", "shift_backward")
        if nonexistent not in nonexistent_options and not isinstance(
            nonexistent, timedelta
        ):
            raise ValueError(
                "The nonexistent argument must be one of 'raise', "
                "'NaT', 'shift_forward', 'shift_backward' or "
                "a timedelta object"
            )

        if self.tz is not None:
            if tz is None:
                new_dates = tz_convert_from_utc(self.asi8, self.tz, reso=self._creso)
            else:
                raise TypeError("Already tz-aware, use tz_convert to convert.")
        else:
            tz = timezones.maybe_get_tz(tz)
            # Convert to UTC

            new_dates = tzconversion.tz_localize_to_utc(
                self.asi8,
                tz,
                ambiguous=ambiguous,

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Use one of: 'raise', 'NaT', 'shift_forward', 'shift_backward'.
2. Or pass a pd.Timedelta / datetime.timedelta to shift by a fixed amount, e.g. nonexistent=pd.Timedelta('1h').
3. Check spelling and case — options are lowercase with underscores.

Example fix

# before
s.dt.tz_localize('Europe/Warsaw', nonexistent='skip')
# after
s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward')

from datetime import timedelta
ALLOWED = {'raise', 'NaT', 'shift_forward', 'shift_backward'}
def validate_nonexistent(opt):
    if opt in ALLOWED or isinstance(opt, timedelta):
        return opt
    raise ValueError(f'invalid nonexistent: {opt!r}')

When it happens

Trigger: Calling .tz_localize('Europe/Warsaw', nonexistent='skip'), or a typo like nonexistent='shift_Forward' (case), or passing an int/str that isn't in the set and isn't a timedelta.

Common situations: Guessing an option name; passing a string from config without validating; copying example code that used an older/imagined API.

Related errors

• Already tz-aware, use tz_convert to convert.
• Cannot compare tz-naive and tz-aware datetime-like objects.
• Cannot compare tz-naive and tz-aware datetime-like objects
• Cannot convert tz-naive timestamps, use tz_localize to local
• DatetimeIndex has mixed timezones

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