{"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":327,"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":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/timedeltas.py#L309-L345","documentation":"Raised by TimedeltaArray._unbox_scalar when the value is neither an instance of self._scalar_type (Timedelta) nor the NaT sentinel. TimedeltaArray only accepts Timedelta scalars (or NaT) for operations like item()/insert; passing a datetime, int, float, or str forces the caller to convert explicitly via pd.Timedelta(...). This prevents silent unit misinterpretation (e.g. treating a raw int as nanoseconds vs seconds).","triggerScenarios":"Calling `td_arr[0] = 5`, `td_arr.item() = datetime.now()`, or any scalar-setting path with a non-Timedelta. The check at timedeltas.py:326 is `not isinstance(value, self._scalar_type) and value is not NaT`.","commonSituations":"Assigning raw integers/floats assuming nanosecond semantics; passing datetime where timedelta was expected; mixing py objects into a typed array.","solutions":["Wrap the value in pd.Timedelta: `td_arr[i] = pd.Timedelta(value, unit='s')`.","Use pd.NaT for missing rather than None or 0.","If passing ints with known units, convert via pd.to_timedelta(value, unit=...)."],"exampleFix":"# before\narr[0] = 60  # ValueError, ambiguous units\n# after\narr[0] = pd.Timedelta(60, unit='s')","handlingStrategy":"type-guard","validationCode":"import pandas as pd\nfrom pandas._libs.tslibs import NaT, Timedelta\n\ndef unbox_td_scalar(arr, value):\n    if value is NaT:\n        return value\n    if not isinstance(value, Timedelta):\n        value = pd.Timedelta(value)\n    return value","typeGuard":"from pandas._libs.tslibs import Timedelta, NaT\ndef is_td_or_nat(value) -> bool:\n    return isinstance(value, Timedelta) or value is NaT","tryCatchPattern":"try:\n    arr[i] = value\nexcept ValueError as e:\n    if 'should be a Timedelta' in str(e):\n        arr[i] = pd.Timedelta(value)\n    else:\n        raise","preventionTips":["Always wrap raw ints/floats in pd.Timedelta with an explicit unit.","Use pd.NaT for missing, never None.","Type-annotate scalar-setting helpers as Timedelta."],"tags":["timedelta","scalar","typeerror","valueerror"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}