apache/cassandra · error · IOException

Corrupted file: integrity check (digest) failed for

Error message

Corrupted file: integrity check (digest) failed for %s: %d != %d

What it means

FileDigestValidator validates a whole file's rolling CRC digest (from a -Digest sidecar) by streaming the file through a CheckedInputStream and comparing the final value with the stored digest line. Mismatch throws this IOException, meaning the file changed or was corrupted since its digest was written.

Solutions

  1. Regenerate the file (or restore from backup/replica) so its digest matches; the existing file cannot be trusted.
  2. Re-create the digest sidecar alongside the file if the file is legitimately new/modified (via FileDigestValidator creation path).
  3. Verify both data file and digest file came from the same snapshot/generation.
  4. Investigate storage integrity (fsck, SMART) if corruption is unexpected.

Example fix

// before
try (FileDigestValidator v = DataIntegrityMetadata.fileDigestValidator(dataFile)) { v.validate(); }
// after
try (FileDigestValidator v = DataIntegrityMetadata.fileDigestValidator(dataFile)) {
    v.validate();
} catch (IOException e) {
    logger.error("Digest mismatch for {}", dataFile, e);
    Files.delete(digestFile); // force regeneration
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

// confirm digest sidecar exists and parse it before full validation
if (!digestFileExists(dataFile)) throw new IOException("Missing digest sidecar for " + dataFile);

Try / catch

try (FileDigestValidator v = DataIntegrityMetadata.fileDigestValidator(dataFile)) { v.validate(); }
catch (IOException e) { regenerateOrRestore(dataFile); }

Prevention

When it happens

Trigger: Calling validate() after fully reading a data file whose computed digest differs from the stored Long parsed from the digest file — full-file corruption, modifications after digest creation, or a digest file from a different generation of the file.

Common situations: Verifying SSTable manifests/components after restore; detecting tampering or bit rot in descriptor files; snapshot restore where the digest sidecar didn't accompany the data file correctly.

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/9d2bdf7a7f3df02a. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/io/util/DataIntegrityMetadata.java:115

        {
            this.dataFile = dataFile;
            this.digestFile = digestFile;
            this.checksum = ChecksumType.CRC32.newInstance();
        }

        // Validate the entire file
        public void validate() throws IOException
        {
            try (RandomAccessReader digestReader = RandomAccessReader.open(digestFile);
                 RandomAccessReader dataReader = RandomAccessReader.open(dataFile);
                 CheckedInputStream checkedInputStream = new CheckedInputStream(dataReader, checksum);)
            {
                long storedDigestValue = Long.parseLong(digestReader.readLine());
                byte[] chunk = new byte[64 * 1024];
                while (checkedInputStream.read(chunk) > 0) ;
                long calculatedDigestValue = checkedInputStream.getChecksum().getValue();
                if (storedDigestValue != calculatedDigestValue)
                    throw new IOException(String.format("Corrupted file: integrity check (digest) failed for %s: %d != %d", dataFile, storedDigestValue, calculatedDigestValue));
            }
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)