{"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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/datetimes.py","lineNumber":1105,"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":1087,"sourceCodeEnd":1123,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/datetimes.py#L1087-L1123","documentation":"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.","triggerScenarios":"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.","commonSituations":"Guessing an option name; passing a string from config without validating; copying example code that used an older/imagined API.","solutions":["Use one of: 'raise', 'NaT', 'shift_forward', 'shift_backward'.","Or pass a pd.Timedelta / datetime.timedelta to shift by a fixed amount, e.g. nonexistent=pd.Timedelta('1h').","Check spelling and case — options are lowercase with underscores."],"exampleFix":"# before\ns.dt.tz_localize('Europe/Warsaw', nonexistent='skip')\n# after\ns.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward')","handlingStrategy":"validation","validationCode":"from datetime import timedelta\nALLOWED = {'raise', 'NaT', 'shift_forward', 'shift_backward'}\ndef validate_nonexistent(opt):\n    if opt in ALLOWED or isinstance(opt, timedelta):\n        return opt\n    raise ValueError(f'invalid nonexistent: {opt!r}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a typed config enum for nonexistent options.","When in doubt default to 'shift_forward' for DST gaps.","Pass pd.Timedelta for fixed shifts."],"tags":["datetime","timezone","dst","tz-localize","pandas"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}