apache/cassandra · error · java.lang.IllegalStateException

Provided dictionary can not be consumed by table's…

Error message

Provided dictionary can not be consumed by table's compressor. Provided dictionary type: ; expected dictionary type by the compressor:

What it means

When a compression dictionary is provided to CQLSSTableWriter, build() additionally checks that the dictionary's kind matches the kind the table's IDictionaryCompressor can consume (e.g. a training vs. serialization dictionary, or zstd vs. another algorithm). A mismatch means the compressor would produce unreadable or invalid SSTables, so an IllegalStateException names both the provided dictionary kind and the expected kind.

Solutions

Regenerate or convert the dictionary so its kind matches compressor.acceptableDictionaryKind() as reported in the message
Verify you are passing the final serialization dictionary, not the training corpus artifact
Ensure the table's compressor class matches the algorithm the dictionary was created for (e.g. zstd dictionary with ZstdCompressor)

Example fix

// before
writer = CQLSSTableWriter.builder()
    .withCompressionDictionary(trainingDictionary) // wrong kind
    .build();
// after
writer = CQLSSTableWriter.builder()
    .withCompressionDictionary(serializedZstdDictionary) // matches compressor.acceptableDictionaryKind()
    .build();

Defensive patterns

Strategy: validation

Validate before calling

if (dict.kind() != ((IDictionaryCompressor) params.getSstableCompressor()).acceptableDictionaryKind())
    throw new IllegalArgumentException("Dictionary kind " + dict.kind() + " != expected " + ((IDictionaryCompressor) params.getSstableCompressor()).acceptableDictionaryKind());

Type guard

boolean kindsMatch = dict.kind() == ((IDictionaryCompressor) compressionParams.getSstableCompressor()).acceptableDictionaryKind();

Try / catch

try { writer = builder.build(); }
catch (IllegalStateException e) {
    if (e.getMessage().contains("Provided dictionary can not be consumed"))
        // regenerate dictionary with the kind named in the message
}

Prevention

Store dictionaries alongside the compressor class they were trained for
Use the same dictionary-management pipeline for training and loading
Validate dictionary kind against acceptableDictionaryKind() before build()

When it happens

Trigger: Calling CQLSSTableWriter.builder() with a dictionary whose IDictionary.kind() differs from compressor.acceptableDictionaryKind() — e.g. passing a zstd training dictionary where a serialization/compression dictionary is required, or a dictionary built for a different compressor class.

Common situations: Reusing dictionaries generated for one compression algorithm/table with another; training a new dictionary but passing the trainer artifact instead of the serialized dictionary; cross-version dictionary files.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/CQLSSTableWriter.java:769

                    KeyspaceMetadata keyspaceMetadata = ClusterMetadata.current().schema.getKeyspaceMetadata(keyspaceName);
                    tableMetadata = keyspaceMetadata.tables.getNullable(tableName);

                    Schema.instance.submit(SchemaTransformations.addTable(tableMetadata, true));
                }

                if (compressionDictionary != null)
                {
                    CompressionParams compressionParams = tableMetadata.params.compression;

                    if (!compressionParams.isDictionaryCompressionEnabled())
                    {
                        throw new IllegalStateException("Table's compressor can not accept any dictionary: " + compressionParams.asMap());
                    }

                    IDictionaryCompressor compressor = (IDictionaryCompressor) compressionParams.getSstableCompressor();
                    if (!compressor.canConsumeDictionary(compressionDictionary))
                    {
                        throw new IllegalStateException("Provided dictionary can not be consumed by table's compressor. " +
                                                        "Provided dictionary type: " + compressionDictionary.kind() +
                                                        "; expected dictionary type by the compressor: " + compressor.acceptableDictionaryKind());
                    }
                }

                ColumnFamilyStore cfs = null;
                if ((buildIndexes && !indexStatements.isEmpty()) || compressionDictionary != null)
                {
                    KeyspaceMetadata keyspaceMetadata = ClusterMetadata.current().schema.getKeyspaceMetadata(keyspaceName);
                    Keyspace keyspace = Keyspace.mockKS(keyspaceMetadata);
                    Directories directories = new Directories(tableMetadata, Collections.singleton(new Directories.DataDirectory(new File(directory.toPath()))));
                    cfs = ColumnFamilyStore.createColumnFamilyStore(keyspace,
                                                                    tableName,
                                                                    tableMetadata,
                                                                    directories,
                                                                    false,
                                                                    false);

View on GitHub (pinned to 88fd0f6a0e)