{"record":{"id":"e82f257babb7488b","repo":"pathwaycom/pathway","slug":"datetimeutc-must-contain-timezone-information-use","errorCode":null,"errorMessage":"DateTimeUtc must contain timezone information. Use pw.DateTimeNaive for naive datetimes.","messagePattern":"DateTimeUtc must contain timezone information\\. Use pw\\.DateTimeNaive for naive datetimes\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/internals/datetime_types.py","lineNumber":24,"sourceCode":"class DateTimeNaive(pd.Timestamp):\n    \"\"\"Type for storing datetime without timezone information. Extends `pandas.Timestamp` type.\"\"\"\n\n    def __new__(cls, *args, **kwargs):\n        obj = super().__new__(cls, *args, **kwargs)\n        if obj.tz is not None:\n            raise ValueError(\n                \"DateTimeNaive cannot contain timezone information. Use pw.DateTimeUtc for datetimes with a timezone.\"\n            )\n        return obj\n\n\nclass DateTimeUtc(pd.Timestamp):\n    \"\"\"Type for storing datetime with default timezone. Extends `pandas.Timestamp` type.\"\"\"\n\n    def __new__(cls, *args, **kwargs):\n        obj = super().__new__(cls, *args, **kwargs)\n        if obj.tz is None:\n            raise ValueError(\n                \"DateTimeUtc must contain timezone information. Use pw.DateTimeNaive for naive datetimes.\"\n            )\n        return obj\n\n\nclass Duration(pd.Timedelta):\n    \"\"\"Type for storing duration of time. Extends `pandas.Timedelta` type.\"\"\"\n\n    pass\n","sourceCodeStart":6,"sourceCodeEnd":34,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/internals/datetime_types.py#L6-L34","documentation":"DateTimeUtc is Pathway's pandas.Timestamp subclass that requires timezone awareness. __new__ raises when the constructed timestamp has tz is None, directing users to DateTimeNaive for wall-clock values. This keeps UTC-typed columns from silently holding ambiguous local times.","triggerScenarios":"pw.DateTimeUtc(\"2024-01-01 10:00:00\") (no offset), pw.DateTimeUtc(pd.Timestamp(\"2024-01-01\")), or a DateTimeUtc-typed column/UDF receiving naive pandas timestamps.","commonSituations":"Source strings without offsets mapped to a DateTimeUtc schema; pandas loading that yields naive timestamps; arithmetic results of naive parsing passed into temporal joins expecting UTC.","solutions":["Localize naive values to UTC before use: pd.to_datetime(series).dt.tz_localize(\"UTC\").","Parse with utc=True up front: pd.to_datetime(series, utc=True).","If the data is intentionally local wall-clock, type the column pw.DateTimeNaive instead."],"exampleFix":"# before\nvalue = pw.DateTimeUtc(pd.Timestamp(\"2024-01-01 10:00:00\"))  # naive -> raises\n\n# after\nvalue = pw.DateTimeUtc(pd.Timestamp(\"2024-01-01 10:00:00\").tz_localize(\"UTC\"))","handlingStrategy":"validation","validationCode":"def to_utc(ts: pd.Timestamp) -> pd.Timestamp:\n    return ts.tz_localize('UTC') if ts.tz is None else ts.tz_convert('UTC')","typeGuard":"import pandas as pd\n\ndef is_aware_timestamp(v) -> bool:\n    return isinstance(v, pd.Timestamp) and v.tz is not None","tryCatchPattern":null,"preventionTips":["Parse with pd.to_datetime(..., utc=True) for UTC columns.","Refuse offset-less strings in sources feeding DateTimeUtc columns; fix at ingestion."],"tags":["pathway","datetime","timezone","schema","type-error"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}