apache/cassandra · error · ConfigurationException

commitlog_segment_size must be at least twice the size of…

Error message

commitlog_segment_size must be at least twice the size of max_mutation_size / 1024

What it means

Thrown when commitlog_segment_size is less than twice max_mutation_size (both in KiB). A commit log segment must be able to hold at least two mutations of maximum size; the explicit max_mutation_size must therefore be at most half the segment size.

Solutions

Raise commitlog_segment_size to at least 2x max_mutation_size, or
lower max_mutation_size to <= commitlog_segment_size / 2, or
remove max_mutation_size so it defaults to commitlog_segment_size / 2.
Restart the node.

Example fix

// before (yaml)
commitlog_segment_size: 32MiB
max_mutation_size: 20MiB
// after
commitlog_segment_size: 64MiB
max_mutation_size: 20MiB

Defensive patterns

Strategy: validation

Validate before calling

Long segKiB = parseKibibytes(yaml.get("commitlog_segment_size"));
Long mutKiB = parseKibibytes(yaml.get("max_mutation_size"));
if (segKiB != null && mutKiB != null && segKiB < 2 * mutKiB)
    throw new IllegalArgumentException("commitlog_segment_size must be >= 2 * max_mutation_size");

Try / catch

try {
    DatabaseDescriptor.applySimpleConfig();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("twice the size of max_mutation_size"))
        logger.error("Raise commitlog_segment_size to >= 2x max_mutation_size");
}

Prevention

Avoid setting max_mutation_size explicitly; it defaults to segment/2
If raising max_mutation_size, raise segment size to at least 2x in the same change
Model the two values as one ratio in config tooling

When it happens

Trigger: cassandra.yaml sets max_mutation_size explicitly such that 2 * max_mutation_size > commitlog_segment_size, e.g. segment 32MiB with max_mutation_size 20MiB. This branch runs only when max_mutation_size is non-null (explicitly configured).

Common situations: Operators raising max_mutation_size for large batches without proportionally raising commitlog_segment_size; copying segment-size defaults from a different config where max_mutation_size was tuned.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

        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);

            if (maxCqlMessageSize > conf.native_transport_max_request_data_in_flight_per_ip.toBytes())
                throw new ConfigurationException("native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip", false);

        }
        nativeTransportMaxMessageSizeInBytes = conf.native_transport_max_message_size.toBytes();

View on GitHub (pinned to 88fd0f6a0e)