{"record":{"id":"b3d28adc30e8f473","repo":"python/cpython","slug":"utcoffset-argument-must-be-a-datetime-instance-o","errorCode":null,"errorMessage":"utcoffset() argument must be a datetime instance or None","messagePattern":"utcoffset\\(\\) argument must be a datetime instance or None","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"Lib/_pydatetime.py","lineNumber":2517,"sourceCode":"        \"datetime.timezone(datetime.timedelta(-1, 68400), 'EST')\"\n        \"\"\"\n        if self is self.utc:\n            return 'datetime.timezone.utc'\n        if self._name is None:\n            return \"%s%s(%r)\" % (_get_class_module(self),\n                                 self.__class__.__qualname__,\n                                 self._offset)\n        return \"%s%s(%r, %r)\" % (_get_class_module(self),\n                                 self.__class__.__qualname__,\n                                 self._offset, self._name)\n\n    def __str__(self):\n        return self.tzname(None)\n\n    def utcoffset(self, dt):\n        if isinstance(dt, datetime) or dt is None:\n            return self._offset\n        raise TypeError(\"utcoffset() argument must be a datetime instance\"\n                        \" or None\")\n\n    def tzname(self, dt):\n        if isinstance(dt, datetime) or dt is None:\n            if self._name is None:\n                return self._name_from_offset(self._offset)\n            return self._name\n        raise TypeError(\"tzname() argument must be a datetime instance\"\n                        \" or None\")\n\n    def dst(self, dt):\n        if isinstance(dt, datetime) or dt is None:\n            return None\n        raise TypeError(\"dst() argument must be a datetime instance\"\n                        \" or None\")\n\n    def fromutc(self, dt):\n        if isinstance(dt, datetime):","sourceCodeStart":2499,"sourceCodeEnd":2535,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_pydatetime.py#L2499-L2535","documentation":"timezone.utcoffset(dt) only accepts a datetime instance or None (None is what some generic tzinfo machinery passes). Because a fixed-offset zone's answer never depends on dt, the argument is still type-checked to honor the tzinfo protocol. Any other type raises TypeError.","triggerScenarios":"tz.utcoffset('2024-01-01'); tz.utcoffset(date(2024,1,1)); tz.utcoffset(0); calling with a datetime.date instead of datetime. Usually hit via custom schedulers passing generic values into tzinfo methods.","commonSituations":"Generic code that forwards whatever it holds into utcoffset; confusing datetime.date with datetime.datetime; porting examples that passed datetimes but the local variable was rebound to a string.","solutions":["Pass a datetime: tz.utcoffset(datetime(2024,1,1)) or None","In generic tzinfo-driven code, only forward datetime or None per the protocol","If you only need the offset of the zone itself, read tz.utcoffset(None)"],"exampleFix":"// before\noff = tz.utcoffset('2024-01-01')\n\n# after\noff = tz.utcoffset(datetime.fromisoformat('2024-01-01'))","handlingStrategy":"type-guard","validationCode":"from datetime import datetime\n\ndef safe_utcoffset(tz, dt):\n    return tz.utcoffset(dt if isinstance(dt, datetime) or dt is None else None)","typeGuard":"from datetime import datetime\n\ndef is_datetime_or_none(v) -> bool:\n    return v is None or isinstance(v, datetime)","tryCatchPattern":null,"preventionTips":["Forward only datetime/None into tzinfo protocol methods","Prefer dt.utcoffset()/dt.astimezone() public wrappers","Use tz.utcoffset(None) to just read a fixed zone's offset"],"tags":["python","datetime","timezone","type-error","api-protocol"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}