{"record":{"id":"a95a617834d812f3","repo":"apache/cassandra","slug":"failed-to-read-a-hint-for-digest-mismatch-for","errorCode":null,"errorMessage":"Failed to read a hint for {} - digest mismatch for hint at position {} in file {}","messagePattern":"Failed to read a hint for (.+?) - digest mismatch for hint at position (.+?) in file (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/hints/HintsReader.java","lineNumber":349,"sourceCode":"\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 readBuffer(size);\n        }\n\n        private ByteBuffer readBuffer(int size) throws IOException\n        {\n            applyThrottleRateLimit(size);\n            input.limit(size);\n\n            ByteBuffer buffer = Hint.serializer.readBufferIfLive(input, now, size, descriptor.messagingVersion());\n            if (input.checkCrc())\n                return buffer;\n\n            // log a warning and skip the corrupted entry\n            logger.warn(\"Failed to read a hint for {} - digest mismatch for hint at position {} in file {}\",\n                        descriptor.hostId,\n                        input.getPosition() - size - 4,\n                        descriptor.fileName());\n            return null;\n        }\n    }\n\n    private static boolean verifyAllZeros(ChecksummedDataInput input) throws IOException\n    {\n        while (!input.isEOF())\n        {\n            if (input.readByte() != 0)\n                return false;\n        }\n        return true;\n    }\n\n    private void applyThrottleRateLimit(int size)","sourceCodeStart":331,"sourceCodeEnd":367,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsReader.java#L331-L367","documentation":"HintsReader reads hints from a hints file and verifies each entry's CRC digest. When the CRC check fails for a hint entry, the reader logs this warning and skips the corrupted entry (returns null) instead of crashing, so remaining hints in the file can still be replayed. It indicates on-disk corruption of one hint record in the hints file for a peer host ID.","triggerScenarios":"Replaying a hints file whose per-entry CRC32 digest does not match the stored CRC — typically caused by disk corruption, an unclean crash while the hint was being written, or manual tampering with the hints file. Raised from readBuffer inside HintsReader's computeNextInternal iteration loop.","commonSituations":"Power loss or OS crash while hints were being written; failing disk sectors; copying hints files between nodes with truncation; hints written with a different messagingVersion being replayed on a mismatched descriptor.","solutions":["Let the node skip the corrupted hint; check logs for how many hints were dropped and whether the file continues to parse.","Verify disk health (smartctl/dmesg) if multiple hints files report digest mismatches.","Run repair (nodetool repair) on the affected ranges to ensure skipped hints' data is re-synced from replicas.","If an entire hints file is corrupt, remove it from the hints directory after the node is stopped so it stops failing to load."],"exampleFix":"// before: hint silently skipped, data may be missing on the destination\nlogger.warn(\"Failed to read a hint for {} - digest mismatch for hint at position {} in file {}\", descriptor.hostId, input.getPosition() - size - 4, descriptor.fileName());\n// after: after replay completes, re-sync the affected ranges\n// nodetool repair -pr <keyspace>  (ensures data carried by the skipped hint is transferred)","handlingStrategy":"retry","validationCode":"import com.sun.jna.Native; // verify hints directory health before restart\n// check filesystem: fsck / smartctl on the hints volume; count corrupt entries from logs","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use reliable storage for the hints directory; monitor disk SMART health.","Always shut nodes down cleanly to avoid torn hint writes.","Run regular repair so skipped hints never cause permanent data divergence.","Alert on repeated 'digest mismatch' warnings — they indicate hardware-level corruption."],"tags":["hints","corruption","crc","disk"],"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"}