pandas-dev/pandas · error · ValueError

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

Error message

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

What it means

Raised by DatetimeArray.tz_localize when the `nonexistent` argument is not one of the allowed strings ('raise', 'NaT', 'shift_forward', 'shift_backward') and is not a datetime.timedelta. The argument controls how to handle wall times that fall inside the 'spring-forward' DST gap (which do not exist locally).

Solutions

Use one of the literal strings: 'raise' (default), 'NaT', 'shift_forward', 'shift_backward'.
For a custom shift, pass a timedelta: `nonexistent=pd.Timedelta('1h')` or `nonexistent=datetime.timedelta(hours=1)`.
If you have a numeric minutes value, wrap it: `nonexistent=pd.Timedelta(minutes=N)`.
To detect the gap explicitly, call tz_localize with 'raise' and catch the NonExistentTimeError, then handle per-row.

Example fix

// before
s.dt.tz_localize('Europe/Warsaw', nonexistent=60)

// after
s.dt.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('60min'))

Defensive patterns

Strategy: validation

Validate before calling

from datetime import timedelta
import pandas as pd

VALID = {'raise', 'NaT', 'shift_forward', 'shift_backward'}
def validate_nonexistent(v):
    if v not in VALID and not isinstance(v, timedelta):
        return 'raise'
    return v

Type guard

def is_valid_nonexistent(v) -> bool:
    from datetime import timedelta
    return v in {'raise', 'NaT', 'shift_forward', 'shift_backward'} or isinstance(v, timedelta)

Try / catch

try:
    out = s.dt.tz_localize(tz, nonexistent=val)
except ValueError as e:
    if 'nonexistent argument' in str(e):
        out = s.dt.tz_localize(tz, nonexistent='NaT')
    else:
        raise

Prevention

Always wrap numeric shifts in pd.Timedelta before passing as `nonexistent`.
When unsure, default to 'NaT' to surface gap rows for inspection.

When it happens

Trigger: Calling `dti.tz_localize('Europe/Warsaw', nonexistent='skip')`, `... nonexistent=0)`, or passing a pandas-dtype object that is not a `datetime.timedelta`. Passing a `pd.Timedelta` works because it subclasses timedelta; passing an int or numpy scalar does not.

Common situations: Copy-pasting an invalid option name from memory ('skip', 'ignore', 'null'). Passing minutes-as-int (e.g. `nonexistent=60`) instead of `pd.Timedelta('60min')`. Older pandas versions lacked the argument entirely, so stale tutorials omit valid values.

Related errors

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

Appendix: source

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

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