apache/cassandra · error · ConfigurationException

native_transport_max_message_size must not exceed native_tra

Error message

native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip

What it means

Cassandra's DatabaseDescriptor validates at startup that native_transport_max_message_size (the largest CQL frame a client may send) is not larger than the per-IP and total in-flight request capacity enforced by the native transport. A frame bigger than the allowed in-flight bytes could never complete, so the library fails fast with this ConfigurationException during applySimpleConfig instead of running with a broken limit.

Source

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

        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 " +
                                                 "configure_jmx function call in cassandra-env.sh or keep cassandra-env.sh " +
                                                 "to call configure_jmx function but you have to keep jmx_server_options " +
                                                 "in cassandra.yaml commented out.");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Lower native_transport_max_message_size_in_bytes so it is <= native_transport_max_request_data_in_flight_per_ip_in_bytes
2. Raise native_transport_max_request_data_in_flight_per_ip_in_bytes (and native_transport_max_request_data_in_flight_in_bytes) to at least the configured max message size
3. Remove both overrides from cassandra.yaml to fall back to default-consistent values

Example fix

# before (cassandra.yaml)
native_transport_max_message_size_in_bytes: 268435456
native_transport_max_request_data_in_flight_per_ip_in_bytes: 67108864
# after
native_transport_max_message_size_in_bytes: 268435456
native_transport_max_request_data_in_flight_per_ip_in_bytes: 536870912

long msgSize = conf.native_transport_max_message_size.toBytes();
if (msgSize > conf.native_transport_max_request_data_in_flight_per_ip.toBytes())
    throw new IllegalArgumentException("native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip");

try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains("native_transport_max_message_size")) { /* adjust limits or fail deployment */ } }

When it happens

Trigger: cassandra.yaml sets native_transport_max_message_size_in_bytes (or native_transport_max_message_size) to a value greater than native_transport_max_request_data_in_flight_per_ip_in_bytes (or the non-per-IP variant) and then DatabaseDescriptor.applyConfig/applySimpleConfig runs (startup or toolInitialization).

Common situations: Operators raising the message size to admit large batches/LOBs without also raising the in-flight limits; copying recommended values from blog posts that tune only one side; upgrades where defaults changed so an old max_message_size now exceeds a lowered in-flight cap.

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

• memtable_cleanup_threshold must be >= 0.01, but was ${conf.m
• memtable_cleanup_threshold must be <= 0.99, but was ${conf.m
• Invalid configuration for cms_commit_retry_strategy.
• Set listen_address OR listen_interface, not both
• Only {} free in the system data volume. Consider adding more

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