{"record":{"id":"2cf80c4b917d4880","repo":"python/cpython","slug":"date-argument-must-be-a-date-instance","errorCode":null,"errorMessage":"date argument must be a date instance","messagePattern":"date argument must be a date instance","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"Lib/_pydatetime.py","lineNumber":1944,"sourceCode":"\n    @classmethod\n    def utcnow(cls):\n        \"Construct a UTC datetime from time.time().\"\n        import warnings\n        warnings.warn(\"datetime.datetime.utcnow() is deprecated and scheduled for \"\n                      \"removal in a future version. Use timezone-aware \"\n                      \"objects to represent datetimes in UTC: \"\n                      \"datetime.datetime.now(datetime.UTC).\",\n                      DeprecationWarning,\n                      stacklevel=2)\n        t = _time.time()\n        return cls._fromtimestamp(t, True, None)\n\n    @classmethod\n    def combine(cls, date, time, tzinfo=True):\n        \"Construct a datetime from a given date and a given time.\"\n        if not isinstance(date, _date_class):\n            raise TypeError(\"date argument must be a date instance\")\n        if not isinstance(time, _time_class):\n            raise TypeError(\"time argument must be a time instance\")\n        if tzinfo is True:\n            tzinfo = time.tzinfo\n        return cls(date.year, date.month, date.day,\n                   time.hour, time.minute, time.second, time.microsecond,\n                   tzinfo, fold=time.fold)\n\n    @classmethod\n    def fromisoformat(cls, date_string):\n        \"\"\"Construct a datetime from a string in one of the ISO 8601 formats.\"\"\"\n        if not isinstance(date_string, str):\n            raise TypeError('fromisoformat: argument must be str')\n\n        if len(date_string) < 7:\n            raise ValueError(f'Invalid isoformat string: {date_string!r}')\n\n        # Split this at the separator","sourceCodeStart":1926,"sourceCodeEnd":1962,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_pydatetime.py#L1926-L1962","documentation":"Raised by datetime.combine() when the first argument is not a date instance. combine(date, time) assembles a datetime by reading date.year/month/day from the first parameter and clock fields from the second; it explicitly isinstance-checks both against _date_class and _time_class, so a string, tuple, or timestamp number for the date part is rejected.","triggerScenarios":"datetime.combine('2024-06-01', time(9,0)); datetime.combine((2024,6,1), t); datetime.combine(datetime_field.date() is forgotten and the datetime itself... (a datetime IS a date, so that passes) — but date strings, structs, or None fail; passing a pandas period or custom date-like lacking the interface.","commonSituations":"Form/API handlers receiving dates as strings and combining directly without parsing; using a tuple from strptime/struct_time; dateutil parsed fields; ORM values that arrive as strings.","solutions":["Parse the date first: datetime.combine(date.fromisoformat('2024-06-01'), t)","Use datetime.strptime('2024-06-01 09:00', '%Y-%m-%d %H:%M') to build both parts in one step","If you already have a datetime, call .replace(hour=..., minute=...) instead of combine"],"exampleFix":"# before\ndt = datetime.combine('2024-06-01', time(9, 0))\n\n# after\nfrom datetime import date\ndt = datetime.combine(date.fromisoformat('2024-06-01'), time(9, 0))","handlingStrategy":"type-guard","validationCode":"from datetime import date as _date, time as _time\nif not isinstance(d, _date):\n    d = _date.fromisoformat(d) if isinstance(d, str) else _date(*d)\nassert isinstance(t, _time)\ndt = datetime.combine(d, t)","typeGuard":"from datetime import date as _date\n\ndef is_date_instance(v) -> bool:\n    return isinstance(v, _date)","tryCatchPattern":"try:\n    dt = datetime.combine(d, t)\nexcept TypeError:\n    dt = datetime.combine(_date.fromisoformat(d), t)  # when d was a str","preventionTips":["Parse date strings at the API boundary, never inside combine calls","Keep a single to_date()/to_time() coercion utility for external data","Use strptime for full 'date time' strings instead of splitting into combine"],"tags":["datetime","combine","typeerror","parsing"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}