{"record":{"id":"d7ade1351ba06773","repo":"apache/cassandra","slug":"some-timestamps-are-larger-than-python-datetime-ca","errorCode":null,"errorMessage":"Some timestamps are larger than Python datetime can represent. Timestamps are displayed in milliseconds from epoch.","messagePattern":"Some timestamps are larger than Python datetime can represent\\. Timestamps are displayed in milliseconds from epoch\\.","errorType":"console","errorClass":"DateOverFlowWarning","httpStatus":null,"severity":"warning","filePath":"pylib/cqlshlib/cqlshmain.py","lineNumber":2189,"sourceCode":"    elif os.path.exists('/usr/share/doc/cassandra/CQL.html'):\n        # fallback to package file\n        cqldocs_url = 'file:///usr/share/doc/cassandra/CQL.html'\n    return cqldocs_url\n\n\ndef insert_driver_hooks():\n\n    class DateOverFlowWarning(RuntimeWarning):\n        pass\n\n    # Display milliseconds when datetime overflows (CASSANDRA-10625), E.g., the year 10000.\n    # Native datetime types blow up outside datetime.[MIN|MAX]_YEAR. We will fall back to an int timestamp\n    def deserialize_date_fallback_int(byts, protocol_version):\n        timestamp_ms = int64_unpack(byts)\n        try:\n            return datetime_from_timestamp(timestamp_ms / 1000.0)\n        except OverflowError:\n            warnings.warn(DateOverFlowWarning(\"Some timestamps are larger than Python datetime can represent. \"\n                                              \"Timestamps are displayed in milliseconds from epoch.\"))\n            return timestamp_ms\n\n    cassandra.cqltypes.DateType.deserialize = staticmethod(deserialize_date_fallback_int)\n\n    if hasattr(cassandra, 'deserializers'):\n        del cassandra.deserializers.DesDateType\n\n    # Return cassandra.cqltypes.EMPTY instead of None for empty values\n    cassandra.cqltypes.CassandraType.support_empty_values = True\n\n\ndef main(cmdline, pkgpath):\n    insert_driver_hooks()\n\n    epilog = f\"Connects to {Shell.DEFAULT_HOST}:{Shell.DEFAULT_PORT}  by default. These \\\n    defaults can be changed by setting $CQLSH_HOST and/or $CQLSH_PORT. When a \\\n    host (and optional port number) are given on the command line, they take \\","sourceCodeStart":2171,"sourceCodeEnd":2207,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/pylib/cqlshlib/cqlshmain.py#L2171-L2207","documentation":"cqlsh replaces DateType.deserialize with a fallback that catches OverflowError when a date value falls outside Python datetime's supported year range, warns via DateOverFlowWarning, and returns the raw int milliseconds since epoch instead of a datetime.","triggerScenarios":"SELECT on a date/timestamp column whose stored value exceeds Python datetime.MINYEAR/MAXYEAR when unpacked (timestamp_ms / 1000.0 out of datetime range) — e.g. huge or negative int64 values.","commonSituations":"Rows written by applications storing sentinel values (0, -1, or very large epoch-ms numbers) in date columns; data written with wrong type or by buggy clients.","solutions":["Treat the returned integer as milliseconds-from-epoch and convert it yourself in Python if it is in range for your tooling.","Find and fix rows containing out-of-range values with a query filtering on the suspicious column.","Correct the writing application to store valid dates; delete or update the offending rows."],"exampleFix":"// before\nfrom datetime import datetime\ndt = row.date_col  # may be int\n// after\nval = row.date_col\ndt = val if isinstance(val, datetime) else datetime.fromtimestamp(val / 1000.0) if -62135596800000 < val < 253402300799999 else None","handlingStrategy":"type-guard","validationCode":"# check a value fits python datetime before formatting\nimport datetime\nMIN_MS = -62135596800000\nMAX_MS = 253402300799999\ndef is_representable(ts_ms): return MIN_MS <= ts_ms <= MAX_MS","typeGuard":"def as_datetime(val):\n    import datetime\n    if isinstance(val, datetime.datetime):\n        return val\n    if isinstance(val, int) and -62135596800000 <= val <= 253402300799999:\n        return datetime.datetime.utcfromtimestamp(val / 1000.0)\n    return None  # out-of-range overflow value","tryCatchPattern":"import warnings\nwith warnings.catch_warnings(record=True) as w:\n    warnings.simplefilter(\"always\")\n    result = session.execute(\"SELECT date_col FROM t\")\n    if any(issubclass(x.category, DateOverFlowWarning) for x in w):\n        handle_overflow_rows(result)","preventionTips":["Never store sentinel or bogus int64 values in date/timestamp columns.","Validate timestamps at write time in the application layer.","Treat int results from cqlsh date columns as milliseconds-from-epoch."],"tags":["python","cqlsh","datetime","deserialization"],"backgroundTag":"value-out-of-range","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}