apache/cassandra · error · ConfigurationException

native_transport_max_message_size must not exceed…

Error message

native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight

What it means

Thrown when native_transport_max_message_size is explicitly configured larger than native_transport_max_request_data_in_flight. The in-flight data limit bounds how many bytes the native protocol can buffer per request, so it must be at least as large as the maximum allowed message size; otherwise valid messages could never complete.

Solutions

Raise native_transport_max_request_data_in_flight to >= native_transport_max_message_size, or
lower native_transport_max_message_size to <= the in-flight limit (also check native_transport_max_request_data_in_flight_per_ip, a similar check follows).
Restart the node.

Example fix

# before
native_transport_max_message_size: 256MiB
native_transport_max_request_data_in_flight: 16MiB
# after
native_transport_max_message_size: 256MiB
native_transport_max_request_data_in_flight: 256MiB

Defensive patterns

Strategy: validation

Validate before calling

Long msgBytes = parseBytes(yaml.get("native_transport_max_message_size"));
Long inflightBytes = parseBytes(yaml.get("native_transport_max_request_data_in_flight"));
if (msgBytes != null && inflightBytes != null && msgBytes > inflightBytes)
    throw new IllegalArgumentException("native_transport_max_message_size must be <= native_transport_max_request_data_in_flight");

Try / catch

try {
    DatabaseDescriptor.applySimpleConfig();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("native_transport_max_message_size must not exceed"))
        logger.error("Raise in-flight limit or lower max message size (also check the per-ip limit)");
}

Prevention

When raising native_transport_max_message_size, raise both in-flight limits in the same change
Leave native_transport_max_message_size unset unless large messages are required
Validate all three related values together in config linting

When it happens

Trigger: cassandra.yaml sets native_transport_max_message_size (e.g. 256MiB) greater than native_transport_max_request_data_in_flight (e.g. 16MiB). Only checked when the message size was set explicitly (nativeTransportMaxMessageSizeConfiguredExplicitly path).

Common situations: Operators raising the CQL message size limit for large batches/inserts but leaving the default in-flight cap; partial copies of a tuned config where only one of the three related options was carried over.

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

Appendix: source

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

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

        // native transport encryption options
        if (conf.client_encryption_options != null)
            conf.client_encryption_options.applyConfig();

        if (conf.jmx_server_options == null)
        {
            conf.jmx_server_options = JMXServerOptions.createParsingSystemProperties();
        }
        else if (JMXServerOptions.isEnabledBySystemProperties())
        {
                throw new ConfigurationException("Configure either jmx_server_options in cassandra.yaml and comment out " +

View on GitHub (pinned to 88fd0f6a0e)