{"record":{"id":"391b2934f16fb09b","repo":"apache/cassandra","slug":"digest-mismatch-exception-391b29","errorCode":null,"errorMessage":"Digest mismatch exception","messagePattern":"Digest mismatch exception","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/hints/HintsReader.java","lineNumber":228,"sourceCode":"\n        private Hint computeNextInternal() throws IOException\n        {\n            input.resetCrc();\n            input.resetLimit();\n\n            int size = input.readInt();\n            if (size == 0)\n            {\n                // Avoid throwing IOException when a hint file ends with a run of zeros - this\n                // can happen when hard-rebooting unresponsive machines.\n                if (!verifyAllZeros(input))\n                    throw new IOException(\"Corrupt hint file found\");\n                throw new EOFException(\"Unexpected end of file (size == 0)\");\n            }\n\n            // if we cannot corroborate the size via crc, then we cannot safely skip this hint\n            if (!input.checkCrc())\n                throw new IOException(\"Digest mismatch exception\");\n\n            return readHint(size);\n        }\n\n        private Hint readHint(int size) throws IOException\n        {\n            applyThrottleRateLimit(size);\n            input.limit(size);\n\n            Hint hint;\n            try\n            {\n                hint = Hint.serializer.deserializeIfLive(input, now, size, descriptor.messagingVersion());\n                input.checkLimit(0);\n            }\n            catch (UnknownTableException | CoordinatorBehindException e)\n            {\n                TableId id = ((UnknownTableException) (e instanceof CoordinatorBehindException ? e.getCause() : e)).id;","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsReader.java#L210-L246","documentation":"HintsReader.computeNextInternal throws IOException(\"Digest mismatch exception\") when input.checkCrc() fails: the per-hint CRC stored alongside the entry does not match the bytes read for the declared size. Since the size itself was non-zero, the CRC was the only way to corroborate it; a mismatch means the entry is corrupt and the hint cannot be safely skipped or returned.","triggerScenarios":"Reading a hints file where a hint entry's bytes were corrupted (torn write, bit rot, partial overwrite) so the stored CRC no longer matches; also happens when a reader misparses sizes due to version/format mismatch, desynchronizing the stream.","commonSituations":"Hints files damaged by hard power loss or crash without clean flush; storage corruption; hint files written by an incompatible Cassandra version being read by another; copying files mid-write.","solutions":["Delete or quarantine the corrupt hints file and restart the node/hint delivery.","Verify disk and filesystem health; repeated corruption warrants hardware checks.","Run repair to cover any hints that were lost and never delivered.","Align Cassandra versions across the cluster to avoid descriptor/entry format mismatch."],"exampleFix":"// before\nHint hint = reader.iterator().next(); // IOException: Digest mismatch exception\n// after\ntry\n{\n    for (Hint hint : HintsReader.open(file))\n        deliver(hint);\n}\ncatch (IOException e)\n{\n    logger.warn(\"CRC failure in hints file {}, dropping file\", file, e);\n    Files.deleteIfExists(file);\n}","handlingStrategy":"try-catch","validationCode":"// pre-check: skip files that are still being written or implausibly small\nif (Files.getLastModifiedTime(file).compareTo(lastStartupTime) > 0 && !isActiveFile(file)) skipFile(file);","typeGuard":null,"tryCatchPattern":"try { hint = reader.readHint(size); } catch (IOException e) { if (e.getMessage().contains(\"Digest mismatch\")) dropCorruptFile(); else throw e; }","preventionTips":["Keep Cassandra versions consistent so hint entry framing/CRC layout matches between reader and writer.","Avoid hard power loss; use proper drain/stop and reliable storage.","Never rsync/scp hints files from a live node.","Repair after corruption events to re-cover undelivered hints."],"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"}