apache/cassandra · error · IOException

Compression dictionary checksum does not match. Expected: %s

Error message

Compression dictionary checksum does not match. Expected: %s; actual: %s

What it means

After reading a serialized compression dictionary's bytes, deserialize recomputes a checksum over (kindOrdinal, id, bytes) and compares it to the stored checksum. A mismatch means the dictionary payload was corrupted in storage or transit, so an IOException is thrown to prevent using broken dictionary data.

Source

Thrown at src/java/org/apache/cassandra/db/compression/CompressionDictionary.java:252

        long id = input.readLong();
        DictId dictId = new DictId(kind, id);

        if (manager != null)
        {
            CompressionDictionary dictionary = manager.get(dictId);
            if (dictionary != null)
            {
                return dictionary;
            }
        }

        int length = input.readInt();
        byte[] dict = new byte[length];
        input.readFully(dict);
        int checksum = input.readInt();
        int calculatedChecksum = calculateChecksum((byte) kindOrdinal, id, dict);
        if (checksum != calculatedChecksum)
            throw new IOException("Compression dictionary checksum does not match. " +
                                  "Expected: " + checksum + "; actual: " + calculatedChecksum);

        CompressionDictionary dictionary = kind.createDictionary(dictId, dict, checksum);

        // update the dictionary manager if it exists
        if (manager != null)
        {
            manager.add(dictionary);
        }

        return dictionary;
    }

    static LightweightCompressionDictionary createFromRowLightweight(UntypedResultSet.Row row)
    {
        String kindStr = row.getString("kind");
        long dictId = row.getLong("dict_id");
        int checksum = row.getInt("dict_checksum");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Re-transfer or re-provision the dictionary file from a healthy source.
2. Delete the corrupted dictionary and regenerate it (re-run dictionary training) so the compressor creates a fresh one.
3. Check hardware/filesystem health (SMART, fsck) if corruption recurs.
4. Restore from backup if the dictionary cannot be regenerated.

Example fix

null

try {
    dict = CompressionDictionary.deserialize(input, manager);
} catch (IOException e) {
    if (e.getMessage().contains("checksum does not match")) { quarantineCorruptFile(); regenerateDictionary(); }
    else throw e;
}

When it happens

Trigger: Reading a compression dictionary whose stored checksum differs from calculateChecksum(kindOrdinal, id, dict) — e.g. bit rot, truncated/partial write, or bytes altered between write and read.

Common situations: Failing disk sectors, interrupted file copies of zstd dictionaries, corruption during backup/restore of dictionary files or the system table.

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

• Dictionary length mismatch for %s dict id %d. Expected: %d,
• compressed_read_ahead_buffer_size must be at least 256KiB (s
• Corrupt flags value for clustering prefix (isStatic flag set
• <ConfigurationException message>
• Invalid Columns subset bytes; too many bits set:<encoded>

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