apache/cassandra · error · ChecksumMismatchException

Hints Descriptor CRC Mismatch

Error message

Hints Descriptor CRC Mismatch

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/hints/HintsDescriptor.java:493

        }
        catch (MarshalException e)
        {
            // Couple of options here: up to 4.0 simply returned null and caller failed with NPE.
            // Seems cleaner to throw an exception
            throw new MarshalException("Corrupt HintsDescriptor serialization, problem: " + e.getMessage(), e);
        }
    }

    private static void updateChecksumLong(CRC32 crc, long value)
    {
        updateChecksumInt(crc, (int) (value & 0xFFFFFFFFL));
        updateChecksumInt(crc, (int) (value >>> 32));
    }

    private static void validateCRC(int expected, int actual) throws IOException
    {
        if (expected != actual)
            throw new ChecksumMismatchException("Hints Descriptor CRC Mismatch");
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Delete the corrupt hints file; hinted handoff will simply not deliver those queued hints.
2. Verify disk/filesystem integrity if many files are affected.
3. Never copy live hints files while Cassandra is running; drain/stop the node or snapshot properly.
4. Ensure all nodes run compatible Cassandra versions so descriptor layout matches.

Example fix

// before
descriptor = HintsDescriptor.deserialize(input); // ChecksumMismatchException
// after
try
{
    descriptor = HintsDescriptor.deserialize(input);
}
catch (IOException e)
{
    logger.warn("CRC mismatch, quarantining hints file {}", file, e);
    Files.move(file, quarantine.resolve(file.getFileName()));
}

// check plausible file size and header magic before opening
if (Files.size(hintsFile) < HintsDescriptor.ENCODED_SIZE + 4) skipFile(hintsFile);

try { descriptor = HintsDescriptor.deserialize(input); } catch (ChecksumMismatchException e) { quarantine(file); } catch (IOException e) { throw e; }

When it happens

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

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

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

• Digest mismatch exception
• Digest mismatch exception
• Corrupt HintsDescriptor serialization, problem:
• Corrupt hint file found
• Failed to read a hint for {}: {} - digest mismatch for hint

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