{"record":{"id":"6ecd69d81a203b62","repo":"apache/cassandra","slug":"failed-to-acquire-reference-to-compression-diction-6ecd69","errorCode":null,"errorMessage":"Failed to acquire reference to compression dictionary %s","messagePattern":"Failed to acquire reference to compression dictionary (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/io/compress/CompressionMetadata.java","lineNumber":466,"sourceCode":"        @Nullable // Reference to keep dictionary alive during write\n        private Ref<? extends CompressionDictionary> compressionDictionaryRef;\n\n        private Writer(CompressionParams parameters, File file, CompressionDictionary compressionDictionary)\n        {\n            this.parameters = parameters;\n            this.file = file;\n            this.compressionDictionary = compressionDictionary;\n            // Take a reference to ensure dictionary stays alive during SSTable write\n            if (compressionDictionary != null)\n            {\n                this.compressionDictionaryRef = compressionDictionary.tryRef();\n                if (compressionDictionaryRef == null)\n                {\n                    // Clean up offsets SafeMemory allocated in field initializer before throwing\n                    // to prevent resource leak. The offsets field is initialized before constructor\n                    // body runs, so it must be explicitly cleaned up if construction fails.\n                    offsets.close();\n                    throw new IllegalStateException(\"Failed to acquire reference to compression dictionary \" + compressionDictionary.dictId());\n                }\n            }\n        }\n\n        /**\n         * Creates a new Writer for compression metadata.\n         *\n         * Note on resource management: If this method throws an exception, all resources\n         * are properly cleaned up. The Writer constructor ensures that if dictionary\n         * reference acquisition fails, the offsets SafeMemory is released.\n         */\n        public static Writer open(CompressionParams parameters,\n                                  File file,\n                                  CompressionDictionary compressionDictionary)\n        {\n            return new Writer(parameters, file, compressionDictionary);\n        }\n","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/compress/CompressionMetadata.java#L448-L484","documentation":"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.","triggerScenarios":"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.","commonSituations":"Writing SSTables after dictionaries were dropped/replaced by a schema change; restored backups missing the dictionary directory; races during shutdown or dictionary eviction.","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"],"exampleFix":"// before\nWriter w = new Writer(filePath, parameters, dictionary); // IllegalStateException if ref null\n// after\ntry {\n    Writer w = new Writer(filePath, parameters, dictionary);\n} catch (IllegalStateException e) {\n    logger.error(\"Could not acquire dictionary: {}\", e.getMessage());\n    failOrFallbackToPlainCompression();\n}","handlingStrategy":"try-catch","validationCode":"if (!compressionDictionary.isLoaded())\n    throw new IllegalStateException(\"Dictionary not loaded: \" + compressionDictionary.dictId());","typeGuard":null,"tryCatchPattern":"try { return new Writer(filePath, params, dict); }\ncatch (IllegalStateException e) { logger.error(\"Dict ref failed for {}\", dict.dictId(), e); fallbackCompression(); }","preventionTips":["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"],"tags":["compression-dictionary","reference-counting","constructor","lifecycle"],"backgroundTag":"resource-not-found","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}