apache/cassandra · error · IllegalStateException

Failed to acquire reference to compression dictionary %s

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.

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)

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.