{"record":{"id":"92a9a7b6588ff5d8","repo":"apache/cassandra","slug":"failed-to-read-a-hint-for-digest-mismatch","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":261,"sourceCode":"            }\n            catch (UnknownTableException | CoordinatorBehindException e)\n            {\n                TableId id = ((UnknownTableException) (e instanceof CoordinatorBehindException ? e.getCause() : e)).id;\n                logger.warn(\"Failed to read a hint for {}: {} - table with id {} is unknown in file {}\",\n                            StorageService.instance.getEndpointForHostId(descriptor.hostId),\n                            descriptor.hostId,\n                            id,\n                            descriptor.fileName());\n                input.skipBytes(Ints.checkedCast(size - input.bytesPastLimit()));\n\n                hint = null; // set the return value to null and let following code to update/check the CRC\n            }\n\n            if (input.checkCrc())\n                return hint;\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                        StorageService.instance.getEndpointForHostId(descriptor.hostId),\n                        descriptor.hostId,\n                        input.getPosition() - size - 4,\n                        descriptor.fileName());\n            return null;\n        }\n    }\n\n    /**\n     * A verbatim iterator that simply returns the underlying ByteBuffers.\n     */\n    final class BuffersIterator extends AbstractIterator<ByteBuffer>\n    {\n        private final InputPosition offset;\n        private final long now = currentTimeMillis();\n\n        BuffersIterator(InputPosition offset)\n        {","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsReader.java#L243-L279","documentation":"Each hint entry in a hints file is protected by a CRC. After deserializing a hint, the input's checkCrc() verifies the stored digest; on mismatch the hint is discarded: this warning logs the endpoint, hostId, byte position and file, and readHint returns null so the corrupted entry is skipped while replay continues. This protects against bit rot or partial writes corrupting a single record.","triggerScenarios":"checkCrc() returns false for an entry in the hints file — corrupted bytes at position (input.getPosition() - size - 4), typically from disk corruption, torn writes after a crash, or manual file tampering.","commonSituations":"Failing disks or filesystem corruption; power loss causing torn writes; copying hints files between nodes incorrectly.","solutions":["Check the disk/filesystem health on the hints volume (dmesg, smartctl, fsck)","Accept the loss of the single corrupted hint and run a repair on the affected ranges to backfill missed writes","If corruption is widespread, move the corrupt hints files aside and let new ones be created","Ensure clean shutdown procedures to avoid torn writes"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// detect corruption early: verify file CRC headers after unclean shutdown\n// and monitor the hints directory for files changing unexpectedly","typeGuard":null,"tryCatchPattern":"if (!input.checkCrc()) {\n  logger.warn(\"CRC mismatch for hint at {} in {}\", position, file);\n  return null; // skip corrupted entry, continue replay\n}","preventionTips":["Monitor disk health (SMART, dmesg) on the hints volume","Always shut down cleanly to avoid torn writes","After corruption, run repair to backfill the lost hinted writes","Avoid manually copying hints files between nodes"],"tags":["hints","crc","corruption","checksum"],"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"}