{"record":{"id":"f32fa2f40012b835","repo":"apache/cassandra","slug":"numeric-literals-for-date-must-be-between-0-and-d","errorCode":null,"errorMessage":"Numeric literals for DATE must be between 0 and %d (got %d)","messagePattern":"Numeric literals for DATE must be between 0 and (.+?) \\(got (.+?)\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/functions/types/CodecUtils.java","lineNumber":219,"sourceCode":"     */\n    static int fromSignedToUnsignedInt(int signed)\n    {\n        return signed - Integer.MIN_VALUE;\n    }\n\n    /**\n     * Convert from a raw CQL long representing a numeric DATE literal to the number of days since the\n     * Epoch. In CQL, numeric DATE literals are longs (unsigned integers actually) between 0 and 2^32\n     * - 1, with the epoch in the middle; this method re-centers the epoch at 0.\n     *\n     * @param raw The CQL date value to convert.\n     * @return The number of days since the Epoch corresponding to the given raw value.\n     * @throws IllegalArgumentException if the value is out of range.\n     */\n    static int fromCqlDateToDaysSinceEpoch(long raw)\n    {\n        if (raw < 0 || raw > MAX_CQL_LONG_VALUE)\n            throw new IllegalArgumentException(\n            String.format(\n            \"Numeric literals for DATE must be between 0 and %d (got %d)\",\n            MAX_CQL_LONG_VALUE, raw));\n        return (int) (raw - EPOCH_AS_CQL_LONG);\n    }\n\n    private static int sizeOfCollectionSize(ProtocolVersion version)\n    {\n        switch (version)\n        {\n            case V1:\n            case V2:\n                return 2;\n            case V3:\n            case V4:\n            case V5:\n            case V6:\n                return 4;","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/functions/types/CodecUtils.java#L201-L237","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Clamp/validate the raw value to 0..MAX_CQL_LONG_VALUE before calling fromCqlDateToDaysSinceEpoch","Produce raw values via CodecUtils.daysSinceEpochToCqlDate (or LocalDate) instead of manual arithmetic","Use TypeCodec's date codec so encoding/decoding stay symmetric"],"exampleFix":"// before\nint days = CodecUtils.fromCqlDateToDaysSinceEpoch(-5); // raw cannot be negative\n// after\nint days = CodecUtils.fromCqlDateToDaysSinceEpoch(CodecUtils.daysSinceEpochToCqlDate(-5));","handlingStrategy":"validation","validationCode":"if (raw < 0 || raw > CodecUtils.MAX_CQL_LONG_VALUE) {\n    throw new IllegalArgumentException(\"raw date value out of CQL date range: \" + raw);\n}","typeGuard":null,"tryCatchPattern":"try {\n    int days = CodecUtils.fromCqlDateToDaysSinceEpoch(raw);\n} catch (IllegalArgumentException e) {\n    // fix the raw-value encoding source\n}","preventionTips":["Always derive raw date values from the driver's date codec or LocalDate helpers","Never feed millis-since-epoch longs into the CQL date raw conversion","Unit-test any custom date codec against known dates (1970-01-01, max date)"],"tags":["java-driver","date","serialization"],"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"}