{"record":{"id":"c6eead4f61712f36","repo":"pandas-dev/pandas","slug":"value-should-be-a-timedelta","errorCode":null,"errorMessage":"'value' should be a Timedelta.","messagePattern":"'value' should be a Timedelta\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/timedeltas.py","lineNumber":344,"sourceCode":"        if freq is not None:\n            index = generate_regular_range(start, end, periods, freq, unit=unit)\n        else:\n            index = np.linspace(start._value, end._value, periods).astype(\"i8\")\n\n        if not left_closed:\n            index = index[1:]\n        if not right_closed:\n            index = index[:-1]\n\n        td64values = index.view(f\"m8[{unit}]\")\n        return cls._simple_new(td64values, dtype=td64values.dtype)\n\n    # ----------------------------------------------------------------\n    # DatetimeLike Interface\n\n    def _unbox_scalar(self, value) -> np.timedelta64:\n        if not isinstance(value, self._scalar_type) and value is not NaT:\n            raise ValueError(\"'value' should be a Timedelta.\")\n        self._check_compatible_with(value)\n        if value is NaT:\n            return np.timedelta64(value._value, self.unit)\n        else:\n            #  error: Incompatible return value type (got \"timedelta64[timedelta |\n            # int | None] | datetime64[date | int | None]\",\n            # expected \"timedelta64[timedelta | int | None]\")\n            return value.as_unit(self.unit, round_ok=False).asm8  # type: ignore[return-value]\n\n    def _scalar_from_string(self, value) -> Timedelta | NaTType:\n        return Timedelta(value)\n\n    def _check_compatible_with(self, other) -> None:\n        # we don't have anything to validate.\n        pass\n\n    # ----------------------------------------------------------------\n    # Array-Like / EA-Interface Methods","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/timedeltas.py#L326-L362","documentation":"TimedeltaArray._unbox_scalar raises ValueError when the supplied value is neither a Timedelta nor NaT. Operations that need to compare or set a scalar against the array require the scalar to be a Timedelta (or NaT) so the resolution can be aligned; passing int, float, str, or datetime is rejected.","triggerScenarios":"Internal call _unbox_scalar(5) or _unbox_scalar('1 day') on a TimedeltaArray; comparison ops that route non-Timedelta scalars through _unbox_scalar; setitem with a Python int.","commonSituations":"Passing an integer meant as nanoseconds directly; passing a string instead of pd.Timedelta(...); using a datetime where a timedelta was expected.","solutions":["Wrap the value in pd.Timedelta first: pd.Timedelta(value).","Use pd.NaT for missing scalars.","If the value is an integer in a known unit, construct pd.Timedelta(value, unit='ns')."],"exampleFix":"// before\narr._unbox_scalar(5)  # ValueError\n// after\narr._unbox_scalar(pd.Timedelta(5, unit='ns'))","handlingStrategy":"type-guard","validationCode":"def unbox_td_scalar(arr, value):\n    import pandas as pd\n    if not isinstance(value, (pd.Timedelta, type(pd.NaT))):\n        value = pd.Timedelta(value)\n    return arr._unbox_scalar(value)","typeGuard":"def is_timedelta_or_nat(value) -> bool:\n    import pandas as pd\n    return isinstance(value, pd.Timedelta) or value is pd.NaT","tryCatchPattern":"try:\n    arr._unbox_scalar(value)\nexcept ValueError as e:\n    if \"should be a Timedelta\" in str(e):\n        arr._unbox_scalar(pd.Timedelta(value))\n    else:\n        raise","preventionTips":["Wrap raw ints/strings in pd.Timedelta before passing.","Use pd.NaT for missing scalars.","Specify the unit when constructing from ints: pd.Timedelta(value, unit='ns')."],"tags":["pandas","timedelta","scalar","type-error","internal"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}