{"record":{"id":"e935f11434cb3ead","repo":"apache/cassandra","slug":"chunk-length-in-kb-must-be-a-power-of-2","errorCode":null,"errorMessage":"chunk_length_in_kb must be a power of 2","messagePattern":"chunk_length_in_kb must be a power of 2","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/schema/CompressionParams.java","lineNumber":466,"sourceCode":"     * @return the value of the {@code enabled} option\n     */\n    private static boolean removeEnabled(Map<String, String> options)\n    {\n        String enabled = options.remove(ENABLED);\n        return enabled == null || Boolean.parseBoolean(enabled);\n    }\n\n    // chunkLength must be a power of 2 because we assume so when\n    // computing the chunk number from an uncompressed file offset (see\n    // CompressedRandomAccessReader.decompresseChunk())\n    public void validate() throws ConfigurationException\n    {\n        // if chunk length was not set (chunkLength == null), this is fine, default will be used\n        if (chunkLength <= 0)\n            throw new ConfigurationException(\"Invalid negative or null \" + CHUNK_LENGTH_IN_KB);\n\n        if ((chunkLength & (chunkLength - 1)) != 0)\n            throw new ConfigurationException(CHUNK_LENGTH_IN_KB + \" must be a power of 2\");\n\n        if (maxCompressedLength < 0)\n            throw new ConfigurationException(\"Invalid negative \" + MIN_COMPRESS_RATIO);\n\n        if (maxCompressedLength > chunkLength && maxCompressedLength < Integer.MAX_VALUE)\n            throw new ConfigurationException(MIN_COMPRESS_RATIO + \" can either be 0 or greater than or equal to 1\");\n    }\n\n    public Map<String, String> asMap()\n    {\n        if (!isEnabled())\n            return Collections.singletonMap(ENABLED, \"false\");\n\n        Map<String, String> options = new HashMap<>(otherOptions);\n        // Use the one saved in the registry, we don't want to save the name of the service provider compressor here!\n        options.put(CLASS, sstableCompressor.serializedAs().getName());\n        options.put(CHUNK_LENGTH_IN_KB, chunkLengthInKB());\n        if (minCompressRatio != DEFAULT_MIN_COMPRESS_RATIO)","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/schema/CompressionParams.java#L448-L484","documentation":"CompressionParams.validate requires chunk_length_in_kb to be a power of 2 because compressed chunk offsets are computed with bit arithmetic (chunk index = offset / chunkLength, aligned 2^n boundaries) in CompressedRandomAccessReader.decompresseChunk(). Non-power-of-2 chunks would corrupt offset math.","triggerScenarios":"Calling validate (via setCompressionParameters or fromMap) with a chunk_length_in_kb that is positive but not a power of two, e.g. 10, 24, 100.","commonSituations":"Guessing a chunk size like '48kb' when tuning compression; migrating configs from other systems that allow arbitrary chunk sizes.","solutions":["Choose a power-of-2 value: 4, 8, 16, 32, or 64 KB","Round the intended value up to the nearest power of 2","Remove the option to use the default chunk length"],"exampleFix":"// before\n{'class': 'LZ4Compressor', 'chunk_length_in_kb': '48'}\n// after\n{'class': 'LZ4Compressor', 'chunk_length_in_kb': '64'}","handlingStrategy":"validation","validationCode":"if (Integer.bitCount(kb) != 1) throw new IllegalArgumentException(\"chunk_length_in_kb must be a power of 2, got: \" + kb);","typeGuard":null,"tryCatchPattern":"try { params.validate(); } catch (ConfigurationException e) { log.error(\"chunk length not power of 2\", e); }","preventionTips":["Snap chosen sizes to the nearest power of 2 (4, 8, 16, 32, 64 KB)","Remember offsets use 2^n-aligned chunk boundaries, hence the constraint","Add a unit test asserting power-of-2 acceptance"],"tags":["config","compression","validation"],"backgroundTag":"invalid-config-value","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"}