apache/cassandra · error · ConfigurationException

internode_max_message_size must no exceed…

Error message

internode_max_message_size must no exceed internode_application_receive_queue_reserve_endpoint_capacity

What it means

internode_max_message_size caps the size of messages sent between nodes; it cannot exceed the per-endpoint reserved capacity of the internode application receive queue, or a maximum-size message could never fit in the reserved receive buffer. DatabaseDescriptor throws this ConfigurationException (note the typo 'no exceed' in the message) when maxMessageSize > internode_application_receive_queue_reserve_endpoint_capacity.

Solutions

Lower internode_max_message_size_in_bytes to <= the receive-queue per-endpoint reserve capacity
Or raise internode_application_receive_queue_reserve_endpoint_capacity_in_bytes to at least internode_max_message_size
Remove overrides so defaults (which are mutually consistent) apply

Example fix

# before (cassandra.yaml)
internode_max_message_size_in_bytes: 104857600
internode_application_receive_queue_reserve_endpoint_capacity_in_bytes: 8388608
# after
internode_max_message_size_in_bytes: 104857600
internode_application_receive_queue_reserve_endpoint_capacity_in_bytes: 134217728

Defensive patterns

Strategy: validation

Validate before calling

if (conf.internode_max_message_size != null &&
    conf.internode_max_message_size.toBytes() > conf.internode_application_receive_queue_reserve_endpoint_capacity.toBytes())
    throw new IllegalArgumentException("internode_max_message_size must not exceed receive-queue endpoint reserve");

Try / catch

try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains("receive_queue_reserve_endpoint_capacity")) { /* rebalance limits */ } }

Prevention

Change internode_max_message_size and all four queue-reserve settings together
Keep each queue reserve >= internode_max_message_size
Test config changes with a config-load dry run before rolling to the cluster

When it happens

Trigger: cassandra.yaml sets internode_max_message_size_in_bytes to a value greater than internode_application_receive_queue_reserve_endpoint_capacity_in_bytes while internode_max_message_size is non-null, during applySimpleConfig.

Common situations: Raising internode message size for large mutations/batches without scaling the receive queue reserves; lowering queue reserve memory settings without re-checking message size; defaults drift across versions.

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

Appendix: source

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

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

        if (conf.server_encryption_options != null)
        {
            conf.server_encryption_options.applyConfig();

            if (conf.server_encryption_options.legacy_ssl_storage_port_enabled &&
                conf.server_encryption_options.tlsEncryptionPolicy() == EncryptionOptions.TlsEncryptionPolicy.UNENCRYPTED)
            {
                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.");
            }
        }

        if (conf.internode_max_message_size != null)
        {
            long maxMessageSize = conf.internode_max_message_size.toBytes();

            if (maxMessageSize > conf.internode_application_receive_queue_reserve_endpoint_capacity.toBytes())
                throw new ConfigurationException("internode_max_message_size must no exceed internode_application_receive_queue_reserve_endpoint_capacity", false);

            if (maxMessageSize > conf.internode_application_receive_queue_reserve_global_capacity.toBytes())
                throw new ConfigurationException("internode_max_message_size must no exceed internode_application_receive_queue_reserve_global_capacity", false);

            if (maxMessageSize > conf.internode_application_send_queue_reserve_endpoint_capacity.toBytes())
                throw new ConfigurationException("internode_max_message_size must no exceed internode_application_send_queue_reserve_endpoint_capacity", false);

            if (maxMessageSize > conf.internode_application_send_queue_reserve_global_capacity.toBytes())
                throw new ConfigurationException("internode_max_message_size must no exceed internode_application_send_queue_reserve_global_capacity", false);
        }
        else
        {
            long maxMessageSizeInBytes =
            Math.min(conf.internode_application_receive_queue_reserve_endpoint_capacity.toBytes(),
                     conf.internode_application_send_queue_reserve_endpoint_capacity.toBytes());

            conf.internode_max_message_size = new DataStorageSpec.IntBytesBound(maxMessageSizeInBytes);
        }

View on GitHub (pinned to 88fd0f6a0e)