{"record":{"id":"6696d35b5f993981","repo":"apache/cassandra","slug":"native-transport-max-message-size-must-not-exceed-6696d3","errorCode":null,"errorMessage":"native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip","messagePattern":"native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1146,"sourceCode":"\n        if (conf.max_mutation_size == null)\n            conf.max_mutation_size = new DataStorageSpec.IntKibibytesBound(conf.commitlog_segment_size.toKibibytes() / 2);\n        else if (conf.commitlog_segment_size.toKibibytes() < 2 * conf.max_mutation_size.toKibibytes())\n            throw new ConfigurationException(\"commitlog_segment_size must be at least twice the size of max_mutation_size / 1024\", false);\n\n        if (conf.native_transport_max_message_size == null)\n        {\n            conf.native_transport_max_message_size = new DataStorageSpec.LongBytesBound(calculateDefaultNativeTransportMaxMessageSizeInBytes());\n        }\n        else\n        {\n            nativeTransportMaxMessageSizeConfiguredExplicitly = true;\n            long maxCqlMessageSize = conf.native_transport_max_message_size.toBytes();\n            if (maxCqlMessageSize > conf.native_transport_max_request_data_in_flight.toBytes())\n                throw new ConfigurationException(\"native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight\", false);\n\n            if (maxCqlMessageSize > conf.native_transport_max_request_data_in_flight_per_ip.toBytes())\n                throw new ConfigurationException(\"native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip\", false);\n\n        }\n        nativeTransportMaxMessageSizeInBytes = conf.native_transport_max_message_size.toBytes();\n\n        // native transport encryption options\n        if (conf.client_encryption_options != null)\n            conf.client_encryption_options.applyConfig();\n\n        if (conf.jmx_server_options == null)\n        {\n            conf.jmx_server_options = JMXServerOptions.createParsingSystemProperties();\n        }\n        else if (JMXServerOptions.isEnabledBySystemProperties())\n        {\n                throw new ConfigurationException(\"Configure either jmx_server_options in cassandra.yaml and comment out \" +\n                                                 \"configure_jmx function call in cassandra-env.sh or keep cassandra-env.sh \" +\n                                                 \"to call configure_jmx function but you have to keep jmx_server_options \" +\n                                                 \"in cassandra.yaml commented out.\");","sourceCodeStart":1128,"sourceCodeEnd":1164,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1128-L1164","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Lower native_transport_max_message_size_in_bytes so it is <= native_transport_max_request_data_in_flight_per_ip_in_bytes","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","Remove both overrides from cassandra.yaml to fall back to default-consistent values"],"exampleFix":"# before (cassandra.yaml)\nnative_transport_max_message_size_in_bytes: 268435456\nnative_transport_max_request_data_in_flight_per_ip_in_bytes: 67108864\n# after\nnative_transport_max_message_size_in_bytes: 268435456\nnative_transport_max_request_data_in_flight_per_ip_in_bytes: 536870912","handlingStrategy":"validation","validationCode":"long msgSize = conf.native_transport_max_message_size.toBytes();\nif (msgSize > conf.native_transport_max_request_data_in_flight_per_ip.toBytes())\n    throw new IllegalArgumentException(\"native_transport_max_message_size must not exceed native_transport_max_request_data_in_flight_per_ip\");","typeGuard":null,"tryCatchPattern":"try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains(\"native_transport_max_message_size\")) { /* adjust limits or fail deployment */ } }","preventionTips":["Keep native_transport_max_message_size <= native_transport_max_request_data_in_flight(_per_ip) whenever editing cassandra.yaml","Validate config with a startup dry-run (e.g. cassandra -f in CI) before rollout","When raising message sizes, raise in-flight limits in the same change"],"tags":["cassandra","configuration","startup"],"backgroundTag":"conflicting-config-options","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}