{"record":{"id":"007e59050b9c5891","repo":"apache/cassandra","slug":"invalid-uuid-version-d-for-timeuuid","errorCode":null,"errorMessage":"Invalid UUID version %d for timeuuid","messagePattern":"Invalid UUID version (.+?) for timeuuid","errorType":"validation","errorClass":"MarshalException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/marshal/AbstractTimeUUIDType.java","lineNumber":135,"sourceCode":"        // In addition, TimeUUIDType also touches the low bits of the UUID (see CASSANDRA-8730 and DB-1758).\n        loBits ^= 0x8080808080808080L;\n\n        return UUIDType.makeUuidBytes(accessor, hiBits, loBits);\n    }\n\n    // takes as input 8 signed bytes in native machine order\n    // returns the first byte unchanged, and the following 7 bytes converted to an unsigned representation\n    // which is the same as a 2's complement long in native format\n    public static long signedBytesToNativeLong(long signedBytes)\n    {\n        return signedBytes ^ 0x0080808080808080L;\n    }\n\n    private void verifyVersion(long hiBits)\n    {\n        long version = (hiBits >>> 12) & 0xF;\n        if (version != 1)\n            throw new MarshalException(String.format(\"Invalid UUID version %d for timeuuid\",\n                                                     version));\n    }\n\n    protected static long reorderTimestampBytes(long input)\n    {\n        return (input <<  48)\n               | ((input <<  16) & 0xFFFF00000000L)\n               |  (input >>> 32);\n    }\n\n    protected static long reorderBackTimestampBytes(long input)\n    {\n        // In a time-based UUID the high bits are significantly more shuffled than in other UUIDs - if [X] represents a\n        // 16-bit tuple, [1][2][3][4] should become [3][4][2][1].\n        // See the UUID Javadoc (and more specifically the high bits layout of a Leach-Salz UUID) to understand the\n        // reasoning behind this bit twiddling in the first place (in the context of comparisons).\n        return (input << 32)\n               | ((input >>> 16) & 0xFFFF0000L)","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/marshal/AbstractTimeUUIDType.java#L117-L153","documentation":"verifyVersion checks the UUID version nibble of the high bits and throws when it is not 1. timeuuid values in Cassandra are RFC 4122 version-1 (time-based) UUIDs; any other version stored in a timeuuid column is rejected during comparison or comparable-bytes conversion.","triggerScenarios":"Comparing values of AbstractTimeUUIDType (compareCustom, asComparableBytes) or calling fromComparableBytes with a 16-byte value whose UUID version nibble is not 1 (e.g. version 4 random UUID bytes) stored in a timeuuid column.","commonSituations":"Inserting a random UUID (java.util.UUID.randomUUID()) into a timeuuid column via raw bytes or drivers that don't validate; application code generating non-v1 UUIDs; corrupted binary data.","solutions":["Generate proper version-1 time UUIDs (e.g. UUIDGen.getTimeUUID(), or TimeUUID.Generator) instead of random UUIDs.","Parse/validate client-side: check uuid.version() == 1 before sending to a timeuuid column.","Change the column type to uuid if version-4 UUIDs are intended."],"exampleFix":"// before\nUUID id = UUID.randomUUID(); // version 4\n// after\nUUID id = UUIDGen.getTimeUUID(); // version 1 timeuuid","handlingStrategy":"validation","validationCode":"UUID u = /* candidate */;\nif (u == null || u.version() != 1) throw new IllegalArgumentException(\"timeuuid must be version 1\");","typeGuard":"boolean isTimeUUID(java.util.UUID u) { return u != null && u.version() == 1; }","tryCatchPattern":"catch (MarshalException e) { log.warn(\"non-v1 uuid in timeuuid column: {}\", e.getMessage()); regenerateTimeUUID(); }","preventionTips":["Use UUIDGen.getTimeUUID() (or the driver's timeuuid generator) for timeuuid columns.","Never send UUID.randomUUID() to a timeuuid column.","Centralize UUID creation behind a helper that enforces v1 for timeuuid fields."],"tags":["uuid","serialization","type-validation"],"backgroundTag":"invalid-argument-value","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"}