{"record":{"id":"ae0a1f1fc1a5d897","repo":"pandas-dev/pandas","slug":"nonexistent-is-not-supported-ae0a1f","errorCode":null,"errorMessage":"{nonexistent=} is not supported","messagePattern":"(.+?) is not supported","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/arrow/array.py","lineNumber":4268,"sourceCode":"\n    def _dt_tz_localize(\n        self,\n        tz,\n        ambiguous: TimeAmbiguous = \"raise\",\n        nonexistent: TimeNonexistent = \"raise\",\n    ) -> Self:\n        if ambiguous != \"raise\":\n            raise NotImplementedError(f\"{ambiguous=} is not supported\")\n        nonexistent_pa = {\n            \"raise\": \"raise\",\n            \"shift_backward\": \"earliest\",\n            \"shift_forward\": \"latest\",\n        }.get(\n            nonexistent,  # type: ignore[arg-type]\n            None,\n        )\n        if nonexistent_pa is None:\n            raise NotImplementedError(f\"{nonexistent=} is not supported\")\n        if tz is None:\n            result = pc.local_timestamp(self._pa_array)\n        else:\n            result = pc.assume_timezone(\n                self._pa_array, str(tz), ambiguous=ambiguous, nonexistent=nonexistent_pa\n            )\n        return self._from_pyarrow_array(result)\n\n    def _dt_tz_convert(self, tz) -> Self:\n        if self.dtype.pyarrow_dtype.tz is None:\n            raise TypeError(\n                \"Cannot convert tz-naive timestamps, use tz_localize to localize\"\n            )\n        current_unit = self.dtype.pyarrow_dtype.unit\n        result = self._pa_array.cast(pa.timestamp(current_unit, tz))\n        return self._from_pyarrow_array(result)\n\n","sourceCodeStart":4250,"sourceCodeEnd":4286,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/arrow/array.py#L4250-L4286","documentation":"Raised by ArrowExtensionArray._dt_tz_localize when `nonexistent` is not one of the three mapped values. The pyarrow backend supports only 'raise', 'shift_backward' (mapped to pyarrow 'earliest'), and 'shift_forward' (mapped to 'latest'). Any other value ('NaT', timedelta like '1h', 'shift') triggers NotImplementedError.","triggerScenarios":"Calling `s.dt.tz_localize(\"US/Eastern\", nonexistent=\"NaT\")` or `nonexistent=pd.Timedelta(\"1h\")` on a tz-naive pyarrow timestamp Series whose times fall in a DST spring-forward gap. Reached via dt.tz_localize on timestamp[pyarrow].","commonSituations":"Localizing data into a DST timezone during spring-forward; wanting NaT fill for nonexistent times; porting localize code from numpy backend that supported more nonexistent strategies.","solutions":["Use one of the supported values: 'raise' (default), 'shift_forward', or 'shift_backward'.","Cast to datetime64[ns] for richer nonexistent handling: `s.astype(\"datetime64[ns]\").dt.tz_localize(\"US/Eastern\", nonexistent=\"NaT\")`.","Filter out times in the gap before localizing with nonexistent='raise'.","Localize to UTC first if exact wall-clock mapping is not required."],"exampleFix":"# before\ns.dt.tz_localize(\"US/Eastern\", nonexistent=\"NaT\")  # NotImplementedError\n\n# after\nout = s.astype(\"datetime64[ns]\").dt.tz_localize(\"US/Eastern\", nonexistent=\"NaT\")","handlingStrategy":"validation","validationCode":"SUPPORTED_NONEXISTENT = {\"raise\", \"shift_forward\", \"shift_backward\"}\n\ndef safe_tz_localize(s, tz, ambiguous=\"raise\"):\n    if nonexistent not in SUPPORTED_NONEXISTENT:\n        return s.astype(\"datetime64[ns]\").dt.tz_localize(tz, ambiguous=ambiguous, nonexistent=nonexistent)\n    return s.dt.tz_localize(tz, ambiguous=ambiguous, nonexistent=nonexistent)","typeGuard":"def is_supported_nonexistent(v) -> bool:\n    return v in {\"raise\", \"shift_forward\", \"shift_backward\"}","tryCatchPattern":"try:\n    out = s.dt.tz_localize(tz, nonexistent=nonexistent)\nexcept NotImplementedError:\n    out = s.astype(\"datetime64[ns]\").dt.tz_localize(tz, nonexistent=nonexistent)","preventionTips":["Restrict nonexistent to 'raise'/'shift_forward'/'shift_backward' for pyarrow localize.","Cast to datetime64[ns] when NaT/timedelta fill is required.","Filter DST-gap timestamps before localizing with nonexistent='raise'."],"tags":["pyarrow","datetime-accessor","dst","not-implemented"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}