apache/cassandra · error · IllegalArgumentException

compressed_read_ahead_buffer_size_in_kb must be at least 256

Error message

compressed_read_ahead_buffer_size_in_kb must be at least 256KiB (set to 0 to disable)

What it means

setCompressedReadAheadBufferSizeInKb enforces that the compressed read-ahead buffer is either 0 (feature disabled) or at least 256 KiB. Values in (0, 256) are rejected with IllegalArgumentException because sub-256KiB buffers are not meaningful for the compression read-ahead path.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:3106

    public static void setConcurrentViewBuilders(int value)
    {
        conf.concurrent_materialized_view_builders = value;
    }

    public static int getCompressedReadAheadBufferSize()
    {
        return conf.compressed_read_ahead_buffer_size.toBytes();
    }

    public static int getCompressedReadAheadBufferSizeInKB()
    {
        return conf.compressed_read_ahead_buffer_size.toKibibytes();
    }

    public static void setCompressedReadAheadBufferSizeInKb(int sizeInKb)
    {
        if (sizeInKb < 0 || (sizeInKb > 0 && sizeInKb < 256))
            throw new IllegalArgumentException("compressed_read_ahead_buffer_size_in_kb must be at least 256KiB (set to 0 to disable)");

        conf.compressed_read_ahead_buffer_size = createIntKibibyteBoundAndEnsureItIsValidForByteConversion(sizeInKb, "compressed_read_ahead_buffer_size");
    }

    public static long getMinFreeSpacePerDriveInMebibytes()
    {
        return conf.min_free_space_per_drive.toMebibytes();
    }

    public static long getMinFreeSpacePerDriveInBytes()
    {
        return conf.min_free_space_per_drive.toBytesInLong();
    }

    @VisibleForTesting
    public static long setMinFreeSpacePerDriveInMebibytes(long mebiBytes)
    {
        conf.min_free_space_per_drive = new DataStorageSpec.IntMebibytesBound(mebiBytes);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use 0 to disable read-ahead, or a value >= 256 KiB.
Clamp: if (sizeInKb > 0 && sizeInKb < 256) sizeInKb = 256;
Fix the source calculation producing the small/negative value.

Example fix

// before
DatabaseDescriptor.setCompressedReadAheadBufferSizeInKb(128); // rejected
// after
DatabaseDescriptor.setCompressedReadAheadBufferSizeInKb(256); // minimum allowed, or 0 to disable

Defensive patterns

Strategy: validation

Validate before calling

if (sizeInKb == 0 || sizeInKb >= 256) DatabaseDescriptor.setCompressedReadAheadBufferSizeInKb(sizeInKb); else sizeInKb = sizeInKb > 0 ? 256 : 0;

Type guard

boolean isValidReadAheadKb(int v) { return v == 0 || v >= 256; }

Try / catch

try { DatabaseDescriptor.setCompressedReadAheadBufferSizeInKb(v); } catch (IllegalArgumentException e) { log.warn("read-ahead must be 0 or >=256KiB, got {}", v); }

Prevention

Remember the legal domain is {0} ∪ [256, ∞)
Use 0 explicitly to disable the feature
Check unit assumptions (the setter takes KiB)

When it happens

Trigger: Calling DatabaseDescriptor.setCompressedReadAheadBufferSizeInKb(sizeInKb) with sizeInKb < 0, or with 1..255 (e.g. 128).

Common situations: Operators tuning compressed read-ahead with a too-small value assuming KiB was bytes or that any positive value is legal; automation deriving a small percentage-based buffer; typo'd yaml values.

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/b83c76266647d214. Report an issue: GitHub.