apache/cassandra · warning · DateOverFlowWarning

Some timestamps are larger than Python datetime can…

Error message

Some timestamps are larger than Python datetime can represent. Timestamps are displayed in milliseconds from epoch.

What it means

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.

Solutions

1. Treat the returned integer as milliseconds-from-epoch and convert it yourself in Python if it is in range for your tooling.
2. Find and fix rows containing out-of-range values with a query filtering on the suspicious column.
3. Correct the writing application to store valid dates; delete or update the offending rows.

Example fix

// before
from datetime import datetime
dt = row.date_col  # may be int
// after
val = row.date_col
dt = val if isinstance(val, datetime) else datetime.fromtimestamp(val / 1000.0) if -62135596800000 < val < 253402300799999 else None

# check a value fits python datetime before formatting
import datetime
MIN_MS = -62135596800000
MAX_MS = 253402300799999
def is_representable(ts_ms): return MIN_MS <= ts_ms <= MAX_MS

def as_datetime(val):
    import datetime
    if isinstance(val, datetime.datetime):
        return val
    if isinstance(val, int) and -62135596800000 <= val <= 253402300799999:
        return datetime.datetime.utcfromtimestamp(val / 1000.0)
    return None  # out-of-range overflow value

import warnings
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    result = session.execute("SELECT date_col FROM t")
    if any(issubclass(x.category, DateOverFlowWarning) for x in w):
        handle_overflow_rows(result)

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• can't interpret %r as a date with format
• Can't open %r for reading: no matching file found
• Can't open %r for reading
• Cannot deserialize index summary from
• Cannot insert null value for primary key column

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/d7ade1351ba06773. Report an issue: GitHub.

Appendix: source

Thrown at pylib/cqlshlib/cqlshmain.py:2189

    elif os.path.exists('/usr/share/doc/cassandra/CQL.html'):
        # fallback to package file
        cqldocs_url = 'file:///usr/share/doc/cassandra/CQL.html'
    return cqldocs_url


def insert_driver_hooks():

    class DateOverFlowWarning(RuntimeWarning):
        pass

    # Display milliseconds when datetime overflows (CASSANDRA-10625), E.g., the year 10000.
    # Native datetime types blow up outside datetime.[MIN|MAX]_YEAR. We will fall back to an int timestamp
    def deserialize_date_fallback_int(byts, protocol_version):
        timestamp_ms = int64_unpack(byts)
        try:
            return datetime_from_timestamp(timestamp_ms / 1000.0)
        except OverflowError:
            warnings.warn(DateOverFlowWarning("Some timestamps are larger than Python datetime can represent. "
                                              "Timestamps are displayed in milliseconds from epoch."))
            return timestamp_ms

    cassandra.cqltypes.DateType.deserialize = staticmethod(deserialize_date_fallback_int)

    if hasattr(cassandra, 'deserializers'):
        del cassandra.deserializers.DesDateType

    # Return cassandra.cqltypes.EMPTY instead of None for empty values
    cassandra.cqltypes.CassandraType.support_empty_values = True


def main(cmdline, pkgpath):
    insert_driver_hooks()

    epilog = f"Connects to {Shell.DEFAULT_HOST}:{Shell.DEFAULT_PORT}  by default. These \
    defaults can be changed by setting $CQLSH_HOST and/or $CQLSH_PORT. When a \
    host (and optional port number) are given on the command line, they take \

View on GitHub (pinned to 88fd0f6a0e)