apache/cassandra · error · UnsupportedOperationException

Table <keyspaceName>.<tableName> does not support dictionary

Error message

Table <keyspaceName>.<tableName> does not support dictionary compression

What it means

CompressionDictionaryManager.train() refuses to start dictionary training when dictionary compression is not enabled for the table (isEnabled is false). Training requires an active dictionary-capable compression configuration, so the call fails fast with UnsupportedOperationException rather than proceeding.

Source

Thrown at src/java/org/apache/cassandra/db/compression/CompressionDictionaryManager.java:180

    @Override
    public void onNewDictionaryTrained(CompressionDictionary.DictId dictionaryId)
    {
        eventHandler.onNewDictionaryTrained(dictionaryId);
    }

    @Override
    public void onNewDictionaryAvailable(CompressionDictionary.DictId dictionaryId)
    {
        eventHandler.onNewDictionaryAvailable(dictionaryId);
    }

    @Override
    public synchronized void train(boolean force, Map<String, String> parameters)
    {
        // Validate table supports dictionary compression
        if (!isEnabled)
        {
            throw new UnsupportedOperationException("Table " + keyspaceName + '.' + tableName + " does not support dictionary compression");
        }

        // resolve training config and fail fast when invalid, so we do not reach logic which would e.g. flush unnecessarily.
        CompressionDictionaryTrainingConfig trainingConfig = createTrainingConfig(parameters);

        LightweightCompressionDictionary dictionary = retrieveLightweightLatestCompressionDictionary(columnFamilyStore.getKeyspaceName(),
                                                                                                     columnFamilyStore.getTableName(),
                                                                                                     columnFamilyStore.metadata.id.toLongString());

        checkTrainingFrequency(dictionary, trainingConfig);

        // SSTable-based training: sample from existing SSTables

        // this is not closed here but in training runnable when finished
        // also, if view is empty, and we throw just below because of it then
        // there is nothing to "release" so close is not necessary
        ColumnFamilyStore.RefViewFragment refViewFragment = columnFamilyStore.selectAndReference(View.selectFunction(SSTableSet.CANONICAL));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Enable dictionary compression on the table (e.g. ALTER TABLE ... WITH compression = { 'class': '<dictionary-capable compressor>' }) before training.
2. Check the table's current compression settings with DESCRIBE TABLE or the schema tables to confirm the compressor supports dictionaries.
3. Skip the table in automation when dictionary compression is not enabled.
4. Upgrade/reconfigure to a Cassandra build that supports compression dictionaries if the feature is unavailable.

Example fix

// before
cfs.getCompressionDictionaryManager().train(true, Map.of()); // fails on non-dictionary table
// after
ALTER TABLE ks.tbl WITH compression = {'class': 'org.apache.cassandra.io.compress.ZstdDictionaryCompressor'};
if (manager.isEnabled) manager.train(true, Map.of());

if (manager.isEnabled) manager.train(force, params); else logger.warn("Skipping training: dictionary compression disabled for table");

try { manager.train(force, params); } catch (UnsupportedOperationException e) { /* table lacks dictionary compression: enable or skip */ }

When it happens

Trigger: Calling CompressionDictionaryManager.train(force, parameters) — directly or via JMX — on a table whose compression parameters are not a dictionary-capable compressor (e.g. default LZ4/Snappy/Deflate without the dictionary compressor, or dictionary support disabled for the table).

Common situations: Running the training JMX operation against a table that was never created with the dictionary compression option; table compression was altered back to a non-dictionary compressor; tests/automation applying training to all tables indiscriminately.

Related errors

• No SSTables available for training in table <keyspaceName>.<
• The next training or importing can occur only at least after
• Training already in progress for table <keyspaceName>.<table
• Invalid value for %s: %s
• Compressor does not support dictionary training: <compressor

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