apache/cassandra · error · IllegalStateException

Failed to acquire reference to compression dictionary

Error message

Failed to acquire reference to compression dictionary %s

What it means

CompressionMetadata.Writer's constructor acquires a reference to the compression dictionary needed to write new compression metadata. If acquisition fails, it closes the offsets SafeMemory allocated in the field initializer (to prevent a leak since the constructor will not complete) and throws IllegalStateException naming the dictionary id.

Solutions

Ensure the compression dictionary storage is present and unchanged while SSTables referencing it are being written
Re-enable or re-upload the dictionary for the table, or rewrite SSTables with a dictionary-free compression config
Restart the node to rebuild dictionary manager state
If instantiating Writer in tests/tools, guarantee the dictionary is registered before construction and close offsets on failure

Example fix

// before
Writer w = new Writer(filePath, parameters, dictionary); // IllegalStateException if ref null
// after
try {
    Writer w = new Writer(filePath, parameters, dictionary);
} catch (IllegalStateException e) {
    logger.error("Could not acquire dictionary: {}", e.getMessage());
    failOrFallbackToPlainCompression();
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (!compressionDictionary.isLoaded())
    throw new IllegalStateException("Dictionary not loaded: " + compressionDictionary.dictId());

Try / catch

try { return new Writer(filePath, params, dict); }
catch (IllegalStateException e) { logger.error("Dict ref failed for {}", dict.dictId(), e); fallbackCompression(); }

Prevention

Verify dictionary registration before creating writers
Keep dictionaries resident while SSTables using them are written
Avoid schema changes that drop dictionaries mid-write
Close offsets/resources on constructor failure paths

When it happens

Trigger: Creating a Writer for a table configured with compression dictionaries when the dictionary manager cannot return a reference for the given dictId — dictionaries removed, manager closed, or id no longer registered.

Common situations: Writing SSTables after dictionaries were dropped/replaced by a schema change; restored backups missing the dictionary directory; races during shutdown or dictionary eviction.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/compress/CompressionMetadata.java:466

        @Nullable // Reference to keep dictionary alive during write
        private Ref<? extends CompressionDictionary> compressionDictionaryRef;

        private Writer(CompressionParams parameters, File file, CompressionDictionary compressionDictionary)
        {
            this.parameters = parameters;
            this.file = file;
            this.compressionDictionary = compressionDictionary;
            // Take a reference to ensure dictionary stays alive during SSTable write
            if (compressionDictionary != null)
            {
                this.compressionDictionaryRef = compressionDictionary.tryRef();
                if (compressionDictionaryRef == null)
                {
                    // Clean up offsets SafeMemory allocated in field initializer before throwing
                    // to prevent resource leak. The offsets field is initialized before constructor
                    // body runs, so it must be explicitly cleaned up if construction fails.
                    offsets.close();
                    throw new IllegalStateException("Failed to acquire reference to compression dictionary " + compressionDictionary.dictId());
                }
            }
        }

        /**
         * Creates a new Writer for compression metadata.
         *
         * Note on resource management: If this method throws an exception, all resources
         * are properly cleaned up. The Writer constructor ensures that if dictionary
         * reference acquisition fails, the offsets SafeMemory is released.
         */
        public static Writer open(CompressionParams parameters,
                                  File file,
                                  CompressionDictionary compressionDictionary)
        {
            return new Writer(parameters, file, compressionDictionary);
        }

View on GitHub (pinned to 88fd0f6a0e)