What causes "chunk_length_in_kb must be a power of 2" in apache/cassandra?

Choose a power-of-2 value: 4, 8, 16, 32, or 64 KB

apache/cassandra · error · ConfigurationException

chunk_length_in_kb must be a power of 2

Error message

chunk_length_in_kb must be a power of 2

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/schema/CompressionParams.java:466

     * @return the value of the {@code enabled} option
     */
    private static boolean removeEnabled(Map<String, String> options)
    {
        String enabled = options.remove(ENABLED);
        return enabled == null || Boolean.parseBoolean(enabled);
    }

    // chunkLength must be a power of 2 because we assume so when
    // computing the chunk number from an uncompressed file offset (see
    // CompressedRandomAccessReader.decompresseChunk())
    public void validate() throws ConfigurationException
    {
        // if chunk length was not set (chunkLength == null), this is fine, default will be used
        if (chunkLength <= 0)
            throw new ConfigurationException("Invalid negative or null " + CHUNK_LENGTH_IN_KB);

        if ((chunkLength & (chunkLength - 1)) != 0)
            throw new ConfigurationException(CHUNK_LENGTH_IN_KB + " must be a power of 2");

        if (maxCompressedLength < 0)
            throw new ConfigurationException("Invalid negative " + MIN_COMPRESS_RATIO);

        if (maxCompressedLength > chunkLength && maxCompressedLength < Integer.MAX_VALUE)
            throw new ConfigurationException(MIN_COMPRESS_RATIO + " can either be 0 or greater than or equal to 1");
    }

    public Map<String, String> asMap()
    {
        if (!isEnabled())
            return Collections.singletonMap(ENABLED, "false");

        Map<String, String> options = new HashMap<>(otherOptions);
        // Use the one saved in the registry, we don't want to save the name of the service provider compressor here!
        options.put(CLASS, sstableCompressor.serializedAs().getName());
        options.put(CHUNK_LENGTH_IN_KB, chunkLengthInKB());
        if (minCompressRatio != DEFAULT_MIN_COMPRESS_RATIO)

View on GitHub (pinned to 88fd0f6a0e)

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

Example fix

// before
{'class': 'LZ4Compressor', 'chunk_length_in_kb': '48'}
// after
{'class': 'LZ4Compressor', 'chunk_length_in_kb': '64'}

Defensive patterns

Strategy: validation

Validate before calling

if (Integer.bitCount(kb) != 1) throw new IllegalArgumentException("chunk_length_in_kb must be a power of 2, got: " + kb);

Try / catch

try { params.validate(); } catch (ConfigurationException e) { log.error("chunk length not power of 2", e); }

Prevention

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

When it happens

Trigger: 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.

Common situations: Guessing a chunk size like '48kb' when tuning compression; migrating configs from other systems that allow arbitrary chunk sizes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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