{"record":{"id":"b262c4c4230bc841","repo":"apache/cassandra","slug":"hints-descriptor-crc-mismatch","errorCode":null,"errorMessage":"Hints Descriptor CRC Mismatch","messagePattern":"Hints Descriptor CRC Mismatch","errorType":"exception","errorClass":"ChecksumMismatchException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/hints/HintsDescriptor.java","lineNumber":493,"sourceCode":"        }\n        catch (MarshalException e)\n        {\n            // Couple of options here: up to 4.0 simply returned null and caller failed with NPE.\n            // Seems cleaner to throw an exception\n            throw new MarshalException(\"Corrupt HintsDescriptor serialization, problem: \" + e.getMessage(), e);\n        }\n    }\n\n    private static void updateChecksumLong(CRC32 crc, long value)\n    {\n        updateChecksumInt(crc, (int) (value & 0xFFFFFFFFL));\n        updateChecksumInt(crc, (int) (value >>> 32));\n    }\n\n    private static void validateCRC(int expected, int actual) throws IOException\n    {\n        if (expected != actual)\n            throw new ChecksumMismatchException(\"Hints Descriptor CRC Mismatch\");\n    }\n}\n","sourceCodeStart":475,"sourceCodeEnd":496,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsDescriptor.java#L475-L496","documentation":"HintsDescriptor.validateCRC() throws ChecksumMismatchException(\"Hints Descriptor CRC Mismatch\") when the CRC32 stored at the end of the serialized descriptor does not match the CRC computed over the descriptor bytes just read. The descriptor (version, timestamp, hostId, parameters) is CRC-protected; a mismatch means the header bytes were corrupted or the read is misaligned.","triggerScenarios":"Opening a hints file whose first bytes were damaged (partial write, crash during file creation, bit rot) so the computed CRC over channelBufferBytes differs from the trailing expected CRC; reached from HintsDescriptor.deserialize.","commonSituations":"Hints files truncated by hard reboot without fsync; copying hints directories with rsync/scp while a writer was active; storage-level corruption; attempting to read hints written by a different format version (misread lengths → wrong CRC region).","solutions":["Delete the corrupt hints file; hinted handoff will simply not deliver those queued hints.","Verify disk/filesystem integrity if many files are affected.","Never copy live hints files while Cassandra is running; drain/stop the node or snapshot properly.","Ensure all nodes run compatible Cassandra versions so descriptor layout matches."],"exampleFix":"// before\ndescriptor = HintsDescriptor.deserialize(input); // ChecksumMismatchException\n// after\ntry\n{\n    descriptor = HintsDescriptor.deserialize(input);\n}\ncatch (IOException e)\n{\n    logger.warn(\"CRC mismatch, quarantining hints file {}\", file, e);\n    Files.move(file, quarantine.resolve(file.getFileName()));\n}","handlingStrategy":"try-catch","validationCode":"// check plausible file size and header magic before opening\nif (Files.size(hintsFile) < HintsDescriptor.ENCODED_SIZE + 4) skipFile(hintsFile);","typeGuard":null,"tryCatchPattern":"try { descriptor = HintsDescriptor.deserialize(input); } catch (ChecksumMismatchException e) { quarantine(file); } catch (IOException e) { throw e; }","preventionTips":["Stop the node (or use snapshots) before moving/copying hints files between hosts.","Ensure disks/FS are healthy; CRC mismatches often mean hardware-level corruption.","Keep cluster versions homogeneous so the descriptor layout/CRC region is interpreted identically.","Monitor for ChecksumMismatchException in logs and quarantine affected files promptly."],"tags":["java","hints","corruption","crc"],"backgroundTag":"checksum-mismatch","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}