{"record":{"id":"ab3a28ca8297bb33","repo":"pandas-dev/pandas","slug":"of-the-four-parameters-start-end-periods-and-f-ab3a28","errorCode":null,"errorMessage":"Of the four parameters: start, end, periods, and freq, exactly three must be specified","messagePattern":"Of the four parameters: start, end, periods, and freq, exactly three must be specified","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/timedeltas.py","lineNumber":288,"sourceCode":"                unit = np.datetime_data(dtype)[0]\n\n        data = sequence_to_td64ns(data, copy=copy, unit=unit)\n\n        if dtype is not None:\n            data = astype_overflowsafe(data, dtype=dtype, copy=False)\n\n        return cls._simple_new(data, dtype=data.dtype)\n\n    @classmethod\n    def _generate_range(\n        cls, start, end, periods, freq, closed=None, *, unit: TimeUnit\n    ) -> Self:\n        periods = dtl.validate_periods(periods)\n        if freq is None and any(x is None for x in [periods, start, end]):\n            raise ValueError(\"Must provide freq argument if no data is supplied\")\n\n        if com.count_not_none(start, end, periods, freq) != 3:\n            raise ValueError(\n                \"Of the four parameters: start, end, periods, \"\n                \"and freq, exactly three must be specified\"\n            )\n\n        if start is not None:\n            start = Timedelta(start).as_unit(\"ns\")\n\n        if end is not None:\n            end = Timedelta(end).as_unit(\"ns\")\n\n        if unit not in [\"s\", \"ms\", \"us\", \"ns\"]:\n            raise ValueError(\"'unit' must be one of 's', 'ms', 'us', 'ns'\")\n\n        if start is not None and unit is not None:\n            start = start.as_unit(unit, round_ok=False)\n        if end is not None and unit is not None:\n            end = end.as_unit(unit, round_ok=False)\n","sourceCodeStart":270,"sourceCodeEnd":306,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/timedeltas.py#L270-L306","documentation":"Raised by TimedeltaArray._generate_range when com.count_not_none(start, end, periods, freq) != 3. The range-generation contract is 'exactly three of the four must be specified' so the fourth is inferred; specifying fewer (under-determined) or all four (over-determined, contradictory) is ambiguous and rejected. This mirrors date_range's contract.","triggerScenarios":"Calling timedelta_range with only two of {start,end,periods,freq}, or with all four provided. Also when a caller supplies start+end+freq+periods simultaneously.","commonSituations":"Parameterized builders that conditionally set some args to None; copy-paste leaving an extra argument; refactoring from date_range without dropping the now-redundant arg.","solutions":["Provide exactly three of start, end, periods, freq; drop or add one so the count is 3.","If you want inferrable behavior, leave freq=None and pass start+end+periods.","Audit call sites: ensure defaults do not collide (e.g. periods defaulting to a non-None value)."],"exampleFix":"# before\npd.timedelta_range(start='1 day', end='5 days', periods=5, freq='1D')  # 4 args\n# after\npd.timedelta_range(start='1 day', end='5 days', periods=5)","handlingStrategy":"validation","validationCode":"def exactly_three_of_four(start, end, periods, freq):\n    count = sum(x is not None for x in (start, end, periods, freq))\n    if count != 3:\n        raise ValueError(f'Expected exactly 3 of 4, got {count}')\n    return True","typeGuard":"def is_three_of_four(start, end, periods, freq) -> bool:\n    return sum(x is not None for x in (start, end, periods, freq)) == 3","tryCatchPattern":"try:\n    return pd.timedelta_range(start, end, periods, freq)\nexcept ValueError as e:\n    if 'exactly three must be specified' in str(e):\n        return pd.timedelta_range(start=start, end=end, periods=periods)\n    raise","preventionTips":["Make exactly one of the four args None in wrapper defaults.","Add a unit test matrix covering 2/3/4-arg combinations.","Avoid passing both periods and freq unless intentional."],"tags":["timedelta","timedelta-range","argument-validation","valueerror"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}