apache/cassandra · error · IllegalArgumentException

Numeric literals for DATE must be between 0 and

Error message

Numeric literals for DATE must be between 0 and %d (got %d)

What it means

CodecUtils.fromCqlDateToDaysSinceEpoch converts a CQL date raw value (the unsigned 32-bit days-since-epoch encoding, constrained to 0..MAX_CQL_LONG_VALUE) into signed days since the Java Epoch. Values outside the valid CQL date numeric range are rejected with IllegalArgumentException because no valid CQL date can be represented that way.

Solutions

1. Clamp/validate the raw value to 0..MAX_CQL_LONG_VALUE before calling fromCqlDateToDaysSinceEpoch
2. Produce raw values via CodecUtils.daysSinceEpochToCqlDate (or LocalDate) instead of manual arithmetic
3. Use TypeCodec's date codec so encoding/decoding stay symmetric

Example fix

// before
int days = CodecUtils.fromCqlDateToDaysSinceEpoch(-5); // raw cannot be negative
// after
int days = CodecUtils.fromCqlDateToDaysSinceEpoch(CodecUtils.daysSinceEpochToCqlDate(-5));

if (raw < 0 || raw > CodecUtils.MAX_CQL_LONG_VALUE) {
    throw new IllegalArgumentException("raw date value out of CQL date range: " + raw);
}

try {
    int days = CodecUtils.fromCqlDateToDaysSinceEpoch(raw);
} catch (IllegalArgumentException e) {
    // fix the raw-value encoding source
}

When it happens

Trigger: Decoding or converting a date literal from raw bytes with a corrupted/incorrect long value, or manually constructing raw date values (e.g. from a custom serializer) where the long exceeds the CQL date numeric domain.

Common situations: Hand-rolled date codecs producing raw values from java.util.Date millis instead of the CQL date encoding; corrupted binary data from other tools; off-by-one use of the CodecUtils raw-value constants.

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

• Expected 4 byte long for date
• Input date is greater than max supported date
• Input date is less than min supported date
• Invalid type for element, expecting but got
• Native protocol version

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/CodecUtils.java:219

     */
    static int fromSignedToUnsignedInt(int signed)
    {
        return signed - Integer.MIN_VALUE;
    }

    /**
     * Convert from a raw CQL long representing a numeric DATE literal to the number of days since the
     * Epoch. In CQL, numeric DATE literals are longs (unsigned integers actually) between 0 and 2^32
     * - 1, with the epoch in the middle; this method re-centers the epoch at 0.
     *
     * @param raw The CQL date value to convert.
     * @return The number of days since the Epoch corresponding to the given raw value.
     * @throws IllegalArgumentException if the value is out of range.
     */
    static int fromCqlDateToDaysSinceEpoch(long raw)
    {
        if (raw < 0 || raw > MAX_CQL_LONG_VALUE)
            throw new IllegalArgumentException(
            String.format(
            "Numeric literals for DATE must be between 0 and %d (got %d)",
            MAX_CQL_LONG_VALUE, raw));
        return (int) (raw - EPOCH_AS_CQL_LONG);
    }

    private static int sizeOfCollectionSize(ProtocolVersion version)
    {
        switch (version)
        {
            case V1:
            case V2:
                return 2;
            case V3:
            case V4:
            case V5:
            case V6:
                return 4;

View on GitHub (pinned to 88fd0f6a0e)