{"record":{"id":"3d2eed9b80c8169d","repo":"apache/cassandra","slug":"compressed-read-ahead-buffer-size-must-be-at-least","errorCode":null,"errorMessage":"compressed_read_ahead_buffer_size must be at least 256KiB (set to 0 to disable), but was <value>","messagePattern":"compressed_read_ahead_buffer_size must be at least 256KiB \\(set to 0 to disable\\), but was <value>","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1189,"sourceCode":"\n        if (conf.max_value_size.toMebibytes() == 0)\n            throw new ConfigurationException(\"max_value_size must be positive\", false);\n        else if (conf.max_value_size.toMebibytes() >= 2048)\n            throw new ConfigurationException(\"max_value_size must be smaller than 2048, but was \"\n                                             + conf.max_value_size.toString(), false);\n\n        switch (conf.disk_optimization_strategy)\n        {\n            case ssd:\n                diskOptimizationStrategy = new SsdDiskOptimizationStrategy(conf.disk_optimization_page_cross_chance);\n                break;\n            case spinning:\n                diskOptimizationStrategy = new SpinningDiskOptimizationStrategy();\n                break;\n        }\n\n        if (conf.compressed_read_ahead_buffer_size.toKibibytes() > 0 && conf.compressed_read_ahead_buffer_size.toKibibytes() < 256)\n            throw new ConfigurationException(\"compressed_read_ahead_buffer_size must be at least 256KiB (set to 0 to disable), but was \" + conf.compressed_read_ahead_buffer_size, false);\n\n        if (conf.server_encryption_options != null)\n        {\n            conf.server_encryption_options.applyConfig();\n\n            if (conf.server_encryption_options.legacy_ssl_storage_port_enabled &&\n                conf.server_encryption_options.tlsEncryptionPolicy() == EncryptionOptions.TlsEncryptionPolicy.UNENCRYPTED)\n            {\n                throw new ConfigurationException(\"legacy_ssl_storage_port_enabled is true (enabled) with internode encryption disabled (none). Enable encryption or disable the legacy ssl storage port.\");\n            }\n        }\n\n        if (conf.internode_max_message_size != null)\n        {\n            long maxMessageSize = conf.internode_max_message_size.toBytes();\n\n            if (maxMessageSize > conf.internode_application_receive_queue_reserve_endpoint_capacity.toBytes())\n                throw new ConfigurationException(\"internode_max_message_size must no exceed internode_application_receive_queue_reserve_endpoint_capacity\", false);","sourceCodeStart":1171,"sourceCodeEnd":1207,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1171-L1207","documentation":"When compression read-ahead is enabled, the buffer used to read ahead of the compression offset must be either disabled (0) or at least 256 KiB, matching the compression chunk minimum. DatabaseDescriptor throws this ConfigurationException with the actual value when the size is strictly between 0 and 256 KiB.","triggerScenarios":"cassandra.yaml sets compressed_read_ahead_buffer_size_in_kb to a positive value below 256 (e.g. 64) and DatabaseDescriptor.applySimpleConfig runs at startup.","commonSituations":"Misunderstanding the unit (setting 100 meaning 100 KiB but expecting bytes-scale tolerance); tuning down memory usage below the minimum; stale configs from older versions with different minimums.","solutions":["Set compressed_read_ahead_buffer_size_in_kb to 256 or larger","Set it to 0 to explicitly disable compressed read-ahead","Remove the override to use the default (64 MiB)"],"exampleFix":"# before (cassandra.yaml)\ncompressed_read_ahead_buffer_size_in_kb: 100\n# after\ncompressed_read_ahead_buffer_size_in_kb: 0","handlingStrategy":"validation","validationCode":"long kib = conf.compressed_read_ahead_buffer_size.toKibibytes();\nif (kib > 0 && kib < 256) throw new IllegalArgumentException(\"compressed_read_ahead_buffer_size must be 0 or >= 256 KiB\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains(\"compressed_read_ahead_buffer_size\")) { /* set to 0 or >= 256KiB */ } }","preventionTips":["Only tune read-ahead in multiples of the 256 KiB compression chunk floor","Use 0 to disable rather than a small positive buffer","Confirm units (KiB) when copying tuning values"],"tags":["cassandra","configuration","compression"],"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"}