Failed to read a hint for {} - digest mismatch for hint at p

Error message

Failed to read a hint for {} - digest mismatch for hint at position {} in file {}

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/hints/HintsReader.java:349

            // if we cannot corroborate the size via crc, then we cannot safely skip this hint
            if (!input.checkCrc())
                throw new IOException("Digest mismatch exception");

            return readBuffer(size);
        }

        private ByteBuffer readBuffer(int size) throws IOException
        {
            applyThrottleRateLimit(size);
            input.limit(size);

            ByteBuffer buffer = Hint.serializer.readBufferIfLive(input, now, size, descriptor.messagingVersion());
            if (input.checkCrc())
                return buffer;

            // log a warning and skip the corrupted entry
            logger.warn("Failed to read a hint for {} - digest mismatch for hint at position {} in file {}",
                        descriptor.hostId,
                        input.getPosition() - size - 4,
                        descriptor.fileName());
            return null;
        }
    }

    private static boolean verifyAllZeros(ChecksummedDataInput input) throws IOException
    {
        while (!input.isEOF())
        {
            if (input.readByte() != 0)
                return false;
        }
        return true;
    }

    private void applyThrottleRateLimit(int size)

View on GitHub (pinned to 88fd0f6a0e)

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.

Example fix

// before: hint silently skipped, data may be missing on the destination
logger.warn("Failed to read a hint for {} - digest mismatch for hint at position {} in file {}", descriptor.hostId, input.getPosition() - size - 4, descriptor.fileName());
// after: after replay completes, re-sync the affected ranges
// nodetool repair -pr <keyspace>  (ensures data carried by the skipped hint is transferred)

Defensive patterns

Strategy: retry

Validate before calling

import com.sun.jna.Native; // verify hints directory health before restart
// check filesystem: fsck / smartctl on the hints volume; count corrupt entries from logs

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/a95a617834d812f3. Report an issue: GitHub.