apache/cassandra · error · IllegalArgumentException

Dictionary to import has older dictionary id (%s) than the l

Error message

Dictionary to import has older dictionary id (%s) than the latest compression dictionary (%s) for table %s.%s

What it means

Dictionaries are versioned by a monotonically increasing dictId. importCompressionDictionary() rejects an import whose dictId is older than the latest dictionary already active on the table, throwing IllegalArgumentException, to avoid regressing compression quality by rolling back to an obsolete dictionary.

Source

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

                                                      keyspaceName, tableName));

        CompressionDictionary.Kind kind = CompressionDictionary.Kind.valueOf(dataObject.kind);

        if (this.kind != kind)
        {
            throw new IllegalArgumentException(format("It is not possible to import compression dictionaries of kind " +
                                                      "%s into table %s.%s which supports compression dictionaries of kind %s.",
                                                      kind, keyspaceName, tableName, this.kind));
        }

        CompressionDictionary.DictId dictId = new CompressionDictionary.DictId(kind, dataObject.dictId);

        LightweightCompressionDictionary latestCompressionDictionary = retrieveLightweightLatestCompressionDictionary(keyspaceName, tableName, tableId);
        if (latestCompressionDictionary != null)
        {
            if (latestCompressionDictionary.dictId.id > dictId.id)
            {
                throw new IllegalArgumentException(format("Dictionary to import has older dictionary id (%s) than the latest compression dictionary (%s) for table %s.%s",
                                                          dictId.id, latestCompressionDictionary.dictId.id, keyspaceName, tableName));
            }

            checkTrainingFrequency(latestCompressionDictionary, createTrainingConfig(Map.of()));
        }

        handleNewDictionary(kind.createDictionary(dictId, dataObject.dict, dataObject.dictChecksum));
    }

    /**
     * Close all the resources. The method can be called multiple times.
     */
    @Override
    public synchronized void close()
    {
        unregisterMbean();
        closeQuitely(cache, "CompressionDictionaryCache");
        closeQuitely(scheduler, "CompressionDictionaryScheduler");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Export and import the latest dictionary (highest dictId) for the table.
2. Skip the import if the target already has a dictionary with an equal or higher dictId.
3. Retrain to produce a fresh dictionary if only old exports are available.
4. Check the current latest dictId via the manager's JMX attributes before importing.

Example fix

// before
manager.importCompressionDictionary(oldDictionaryData); // dictId 3 < current 5
// after
if (currentLatestDictId <= dictionaryData.dictId)
    manager.importCompressionDictionary(dictionaryData);

long latest = manager.getLatestDictionaryId();
if (dataObject.dictId >= latest) manager.importCompressionDictionary(data);

try { manager.importCompressionDictionary(data); } catch (IllegalArgumentException e) { /* stale dictionary: fetch the newest export */ }

When it happens

Trigger: Calling importCompressionDictionary with a payload whose dictId.id is less than retrieveLightweightLatestCompressionDictionary(...).dictId.id — i.e. re-importing an old exported dictionary after a newer one was trained or imported.

Common situations: Replaying old export files into a cluster that has since trained a newer dictionary; importing dictionaries out of order across multiple nodes; restoring a snapshot dictionary from before a more recent training run.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Computed checksum of dictionary to import (%s) is different
• The compression on table %s.%s is not enabled or SSTable com
• Keyspace and table of a dictionary to import (%s.%s) does no
• It is not possible to import compression dictionaries of kin
• java.lang.Throwable

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