{"record":{"id":"41d234b9fcd11d64","repo":"pandas-dev/pandas","slug":"the-nonexistent-argument-must-be-one-of-raise","errorCode":null,"errorMessage":"The nonexistent argument must be one of 'raise', 'NaT', 'shift_forward', 'shift_backward' or a timedelta object","messagePattern":"The nonexistent argument must be one of 'raise', 'NaT', 'shift_forward', 'shift_backward' or a timedelta object","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/datetimes.py","lineNumber":1103,"sourceCode":"        0   2015-03-29 03:00:00+02:00\n        1   2015-03-29 03:30:00+02:00\n        dtype: datetime64[ns, Europe/Warsaw]\n\n        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_backward')\n        0   2015-03-29 01:59:59.999999999+01:00\n        1   2015-03-29 03:30:00.000000000+02:00\n        dtype: datetime64[ns, Europe/Warsaw]\n\n        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('1h'))\n        0   2015-03-29 03:30:00+02:00\n        1   2015-03-29 03:30:00+02:00\n        dtype: datetime64[ns, Europe/Warsaw]\n        \"\"\"  # noqa: E501\n        nonexistent_options = (\"raise\", \"NaT\", \"shift_forward\", \"shift_backward\")\n        if nonexistent not in nonexistent_options and not isinstance(\n            nonexistent, timedelta\n        ):\n            raise ValueError(\n                \"The nonexistent argument must be one of 'raise', \"\n                \"'NaT', 'shift_forward', 'shift_backward' or \"\n                \"a timedelta object\"\n            )\n\n        if self.tz is not None:\n            if tz is None:\n                new_dates = tz_convert_from_utc(self.asi8, self.tz, reso=self._creso)\n            else:\n                raise TypeError(\"Already tz-aware, use tz_convert to convert.\")\n        else:\n            tz = timezones.maybe_get_tz(tz)\n            # Convert to UTC\n\n            new_dates = tzconversion.tz_localize_to_utc(\n                self.asi8,\n                tz,\n                ambiguous=ambiguous,","sourceCodeStart":1085,"sourceCodeEnd":1121,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/datetimes.py#L1085-L1121","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ns.dt.tz_localize('Europe/Warsaw', nonexistent=60)\n\n// after\ns.dt.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('60min'))","handlingStrategy":"validation","validationCode":"from datetime import timedelta\nimport pandas as pd\n\nVALID = {'raise', 'NaT', 'shift_forward', 'shift_backward'}\ndef validate_nonexistent(v):\n    if v not in VALID and not isinstance(v, timedelta):\n        return 'raise'\n    return v","typeGuard":"def is_valid_nonexistent(v) -> bool:\n    from datetime import timedelta\n    return v in {'raise', 'NaT', 'shift_forward', 'shift_backward'} or isinstance(v, timedelta)","tryCatchPattern":"try:\n    out = s.dt.tz_localize(tz, nonexistent=val)\nexcept ValueError as e:\n    if 'nonexistent argument' in str(e):\n        out = s.dt.tz_localize(tz, nonexistent='NaT')\n    else:\n        raise","preventionTips":["Always wrap numeric shifts in pd.Timedelta before passing as `nonexistent`.","When unsure, default to 'NaT' to surface gap rows for inspection."],"tags":["datetime","timezone","dst","validation","argument"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}