apache/cassandra · error · ConfigurationException

commitlog_segment_size must be smaller than 2048, but was

Error message

commitlog_segment_size must be smaller than 2048, but was <value>

What it means

Thrown when commitlog_segment_size is 2048 MiB or larger. Cassandra caps the segment size below 2 GiB to keep segments addressable with 32-bit offsets and bounded recovery replay; oversized values are rejected at startup.

Solutions

Lower commitlog_segment_size below 2048MiB (e.g. 1024MiB).
If you need larger buffering, tune commitlog_sync settings instead of segment size.
Restart the node.

Example fix

# before
commitlog_segment_size: 4096MiB
# after
commitlog_segment_size: 1024MiB

Defensive patterns

Strategy: validation

Validate before calling

Long mib = parseMebibytes(yaml.get("commitlog_segment_size"));
if (mib != null && mib >= 2048)
    throw new IllegalArgumentException("commitlog_segment_size must be < 2048MiB");

Type guard

boolean isValidSegmentSize(Object v) {
    return v == null || (v instanceof Number && ((Number) v).longValue() < 2048);
}

Try / catch

try {
    DatabaseDescriptor.applySimpleConfig();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("commitlog_segment_size must be smaller than 2048"))
        logger.error("Lower commitlog_segment_size below 2048MiB");
}

Prevention

Cap segment size at 1-2 GiB in config generators
Use commitlog tuning (sync period, max window) rather than giant segments
Range-check the value in pre-deploy linting

When it happens

Trigger: cassandra.yaml sets commitlog_segment_size >= 2048MiB, e.g. 'commitlog_segment_size: 4096MiB'.

Common situations: Operators on high-throughput clusters inflating segment size to reduce rotation; confusion with max_mutation_size sizing rules.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

        if (conf.user_defined_functions_fail_timeout.toMilliseconds() < conf.user_defined_functions_warn_timeout.toMilliseconds())
            throw new ConfigurationException("user_defined_functions_warn_timeout must less than user_defined_function_fail_timeout", false);

        if (!conf.allow_insecure_udfs && !conf.user_defined_functions_threads_enabled)
            throw new ConfigurationException("To be able to set enable_user_defined_functions_threads: false you need to set allow_insecure_udfs: true - this is an unsafe configuration and is not recommended.");

        if (conf.allow_extra_insecure_udfs)
            logger.warn("Allowing java.lang.System.* access in UDFs is dangerous and not recommended. Set allow_extra_insecure_udfs: false to disable.");

        if (conf.scripted_user_defined_functions_enabled)
            throw new ConfigurationException("JavaScript user-defined functions were removed in CASSANDRA-18252. " +
                                             "Hooks are planned to be introduced as part of CASSANDRA-17280");

        if (conf.commitlog_segment_size.toMebibytes() == 0)
            throw new ConfigurationException("commitlog_segment_size must be positive, but was "
                                             + conf.commitlog_segment_size.toString(), false);
        else if (conf.commitlog_segment_size.toMebibytes() >= 2048)
            throw new ConfigurationException("commitlog_segment_size must be smaller than 2048, but was "
                                             + conf.commitlog_segment_size.toString(), false);

        if (conf.max_mutation_size == null)
            conf.max_mutation_size = new DataStorageSpec.IntKibibytesBound(conf.commitlog_segment_size.toKibibytes() / 2);
        else if (conf.commitlog_segment_size.toKibibytes() < 2 * conf.max_mutation_size.toKibibytes())
            throw new ConfigurationException("commitlog_segment_size must be at least twice the size of max_mutation_size / 1024", false);

        if (conf.native_transport_max_message_size == null)
        {
            conf.native_transport_max_message_size = new DataStorageSpec.LongBytesBound(calculateDefaultNativeTransportMaxMessageSizeInBytes());
        }
        else
        {
            nativeTransportMaxMessageSizeConfiguredExplicitly = true;
            long maxCqlMessageSize = conf.native_transport_max_message_size.toBytes();
            if (maxCqlMessageSize > conf.native_transport_max_request_data_in_flight.toBytes())
                throw new ConfigurationException("native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight", false);

View on GitHub (pinned to 88fd0f6a0e)