{"record":{"id":"645df86ecbfb4222","repo":"pandas-dev/pandas","slug":"value-should-be-a-timestamp","errorCode":null,"errorMessage":"'value' should be a Timestamp.","messagePattern":"'value' should be a Timestamp\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/datetimes.py","lineNumber":554,"sourceCode":"                if len(i8values)\n                else 0\n            )\n            if not left_inclusive or not right_inclusive:\n                if not left_inclusive and len(i8values) and i8values[0] == start_i8:\n                    i8values = i8values[1:]\n                if not right_inclusive and len(i8values) and i8values[-1] == end_i8:\n                    i8values = i8values[:-1]\n\n        dt64_values = i8values.view(f\"datetime64[{unit}]\")\n        dtype = tz_to_dtype(tz, unit=unit)\n        return cls._simple_new(dt64_values, dtype=dtype)\n\n    # -----------------------------------------------------------------\n    # DatetimeLike Interface\n\n    def _unbox_scalar(self, value) -> np.datetime64:\n        if not isinstance(value, self._scalar_type) and value is not NaT:\n            raise ValueError(\"'value' should be a Timestamp.\")\n        self._check_compatible_with(value)\n        if value is NaT:\n            return np.datetime64(value._value, self.unit)\n        else:\n            return value.as_unit(self.unit, round_ok=False).asm8\n\n    def _scalar_from_string(self, value) -> Timestamp | NaTType:\n        return Timestamp(value, tz=self.tz)\n\n    def _check_compatible_with(self, other) -> None:\n        if other is NaT:\n            return\n        self._assert_tzawareness_compat(other)\n\n    # -----------------------------------------------------------------\n    # Descriptive Properties\n\n    def _box_func(self, x: np.datetime64) -> Timestamp | NaTType:","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/datetimes.py#L536-L572","documentation":"Raised by DatetimeArray._unbox_scalar when the value passed to setitem/search/etc. is neither an instance of the array's _scalar_type (Timestamp) nor pd.NaT. Internally pandas unboxes scalars to raw datetime64 to compare/store them; a non-Timestamp object (e.g. a python datetime, a string, an int) cannot be unboxed without ambiguity, so it is rejected at this low level.","triggerScenarios":"Indexing/setting a DatetimeArray/DatetimeIndex with a python datetime.datetime, a str, or an int directly through the internal _unbox_scalar path (e.g. idx._unbox_scalar(value)); less commonly hit via public setitem when the value bypasses normal coercion.","commonSituations":"Subclassing/extending DatetimeArray and feeding raw python datetime objects; calling internal methods directly; mixed-type assignment that skips the public coercion layer.","solutions":["Wrap the value: pd.Timestamp(value) before passing.","Use the public setitem / .get_loc / .get_indexer APIs which coerce for you.","If you need NaT semantics, pass pd.NaT explicitly rather than None."],"exampleFix":"// before\nval = datetime.datetime(2020, 1, 1)\nidx._unbox_scalar(val)  # ValueError: 'value' should be a Timestamp.\n\n// after\nval = pd.Timestamp(datetime.datetime(2020, 1, 1))\nidx._unbox_scalar(val)","handlingStrategy":"type-guard","validationCode":"def unbox_for_dt(idx, value):\n    if value is not pd.NaT and not isinstance(value, pd.Timestamp):\n        value = pd.Timestamp(value)\n    return idx._unbox_scalar(value)","typeGuard":"def is_timestamp_or_nat(value) -> bool:\n    return value is pd.NaT or isinstance(value, pd.Timestamp)","tryCatchPattern":"try:\n    raw = idx._unbox_scalar(value)\nexcept ValueError as e:\n    if \"should be a Timestamp\" in str(e):\n        raw = idx._unbox_scalar(pd.Timestamp(value))\n    else:\n        raise","preventionTips":["Always wrap values with pd.Timestamp before low-level datetime array ops.","Prefer public setitem/get_loc APIs that coerce automatically.","Reserve _unbox_scalar for code that has already validated inputs."],"tags":["pandas","datetimearray","scalar","internal","type-error"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}