apache/cassandra · error · IllegalArgumentException

Computed checksum of dictionary to import (%s) is different

Error message

Computed checksum of dictionary to import (%s) is different from checksum specified on input (%s).

What it means

When importing a compression dictionary, Cassandra recomputes the checksum of the dictionary bytes (combined with the dictionary kind ordinal and dict id) via CompressionDictionary.calculateChecksum and compares it against the checksum supplied in the import data. If they differ, the input is corrupt or the metadata was edited, and the import is rejected with IllegalArgumentException. This protects nodes from loading a dictionary whose contents do not match what was originally trained.

Source

Thrown at src/java/org/apache/cassandra/db/compression/CompressionDictionaryDetailsTabularData.java:321

            {
                dictionaryKind = CompressionDictionary.Kind.valueOf(kind);
            }
            catch (IllegalArgumentException ex)
            {
                throw new IllegalArgumentException("There is no such dictionary kind like '" + kind + "'. Available kinds: " + Arrays.asList(CompressionDictionary.Kind.values()));
            }

            if (dictLength <= 0)
                throw new IllegalArgumentException("Size has to be strictly positive number, it is '" + dictLength + "'.");
            if (dict.length != dictLength)
                throw new IllegalArgumentException("The length of the provided dictionary array (" + dict.length + ") is not equal to provided length value (" + dictLength + ").");
            if (createdAt == null)
                throw new IllegalArgumentException("The creation date not specified.");

            int checksumOfDictionaryToImport = CompressionDictionary.calculateChecksum((byte) dictionaryKind.ordinal(), dictId, dict);
            if (checksumOfDictionaryToImport != dictChecksum)
            {
                throw new IllegalArgumentException(format("Computed checksum of dictionary to import (%s) is different from checksum specified on input (%s).",
                                                          checksumOfDictionaryToImport,
                                                          dictChecksum));
            }
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Recompute the checksum with CompressionDictionary.calculateChecksum((byte) kind.ordinal(), dictId, dict) and set that value as dictChecksum in the data object before import.
Re-export the dictionary from the source cluster using the provided export tooling instead of copying bytes by hand.
Verify the dictionary bytes were not modified in transit (use binary-safe transfer; avoid text encoding/decoding).
Confirm both source and target run compatible Cassandra versions with the same checksum algorithm.

Example fix

// before
CompressionDictionaryDataObject data = new CompressionDictionaryDataObject(keyspace, table, kind, dictId, dict, staleChecksum);
// after
int checksum = CompressionDictionary.calculateChecksum((byte) dictionaryKind.ordinal(), dictId, dict);
CompressionDictionaryDataObject data = new CompressionDictionaryDataObject(keyspace, table, kind, dictId, dict, checksum);

Defensive patterns

Strategy: validation

Validate before calling

int expected = CompressionDictionary.calculateChecksum((byte) kind.ordinal(), dictId, dict);
if (expected != dataObject.dictChecksum) throw new IllegalArgumentException("checksum mismatch before import");

Try / catch

try { manager.importCompressionDictionary(data); } catch (IllegalArgumentException e) { /* checksum mismatch: re-export dictionary */ }

Prevention

Always export/import dictionaries with the built-in tooling, never hand-copy bytes
Use binary-safe channels for dictionary transfer
Recompute checksums on the exporting side right before export

When it happens

Trigger: Calling CompressionDictionaryManager.importCompressionDictionary (or the JMX/MBean equivalent) with a CompressionDictionaryDataObject whose dictChecksum field does not match CompressionDictionary.calculateChecksum(kind.ordinal(), dictId, dict) computed from the payload.

Common situations: Hand-editing or truncating the dictionary bytes when exporting/importing between clusters; copying dictionary data through a lossy channel (text transformation, wrong encoding); constructing the CompositeData manually with a stale or wrong checksum; exporting from one version and importing into another with a changed checksum algorithm.

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/47b0baeec541e4fb. Report an issue: GitHub.