{"record":{"id":"3b75dfb6298e4808","repo":"apache/cassandra","slug":"native-transport-max-frame-size-must-be-positive-v","errorCode":null,"errorMessage":"native_transport_max_frame_size must be positive value < %dB, but was %dB","messagePattern":"native_transport_max_frame_size must be positive value < (.+?)B, but was (.+?)B","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":788,"sourceCode":"        else\n        {\n            conf.repair_session_max_tree_depth = 20;\n        }\n\n        if (conf.repair_session_space == null)\n            conf.repair_session_space = new DataStorageSpec.IntMebibytesBound(Math.max(1, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));\n\n        if (conf.repair_session_space.toMebibytes() < 1)\n            throw new ConfigurationException(\"repair_session_space must be > 0, but was \" + conf.repair_session_space);\n        else if (conf.repair_session_space.toMebibytes() > (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)))\n            logger.warn(\"A repair_session_space of \" + conf.repair_session_space + \" mebibytes is likely to cause heap pressure\");\n\n        checkForLowestAcceptedTimeouts(conf);\n\n        long valueInBytes = conf.native_transport_max_frame_size.toBytes();\n        if (valueInBytes < 0 || valueInBytes > Integer.MAX_VALUE - 1)\n        {\n            throw new ConfigurationException(String.format(\"native_transport_max_frame_size must be positive value < %dB, but was %dB\",\n                                                           Integer.MAX_VALUE,\n                                                           valueInBytes),\n                                             false);\n        }\n\n        if (conf.column_index_size != null)\n            checkValidForByteConversion(conf.column_index_size, \"column_index_size\");\n        checkValidForByteConversion(conf.column_index_cache_size, \"column_index_cache_size\");\n        checkValidForByteConversion(conf.batch_size_warn_threshold, \"batch_size_warn_threshold\");\n\n        // if data dirs, commitlog dir, or saved caches dir are set in cassandra.yaml, use that.  Otherwise,\n        // use -Dcassandra.storagedir (set in cassandra-env.sh) as the parent dir for data/, commitlog/, and saved_caches/\n        if (conf.commitlog_directory == null)\n        {\n            conf.commitlog_directory = storagedirFor(\"commitlog\");\n        }\n\n        initializeCommitLogDiskAccessMode();","sourceCodeStart":770,"sourceCodeEnd":806,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L770-L806","documentation":"native_transport_max_frame_size limits the size of frames the CQL native protocol will accept. It must fit in a positive signed int (0 < value <= Integer.MAX_VALUE - 1 = 2147483647 bytes). Validation in applySimpleConfig throws ConfigurationException (ignorable=false) so the node will not start with an out-of-range frame size.","triggerScenarios":"Setting native_transport_max_frame_size to a negative value, 0, or >= 2GB (e.g. '4GiB') in cassandra.yaml; validated whenever DatabaseDescriptor is initialized.","commonSituations":"Operators raising the frame size to accommodate large batch inserts who set it to 4GiB or higher; unit-suffix mistakes; configs copied from third-party tuning guides.","solutions":["Set native_transport_max_frame_size to a positive value below 2147483647 bytes (e.g. 256MiB)","Reduce oversized values like 4GiB to something <= Integer.MAX_VALUE - 1","If large payloads are needed, use paging/batching within protocol limits instead of raising frame size"],"exampleFix":"// before (cassandra.yaml)\nnative_transport_max_frame_size: 4GiB\n// after (cassandra.yaml)\nnative_transport_max_frame_size: 256MiB","handlingStrategy":"validation","validationCode":"long bytes = conf.native_transport_max_frame_size.toBytes();\nif (bytes <= 0 || bytes > Integer.MAX_VALUE - 1)\n    throw new IllegalArgumentException(\"native_transport_max_frame_size must be 0 < bytes < 2147483648, got \" + bytes);","typeGuard":null,"tryCatchPattern":"try {\n    DatabaseDescriptor.toolInitialization();\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"native_transport_max_frame_size\"))\n        throw new StartupConfigError(\"frame size must fit in a positive int\", e);\n    throw e;\n}","preventionTips":["Keep native_transport_max_frame_size well under 2GiB (e.g. 256MiB)","Never set 0 or negative frame sizes","Handle large payloads with paging instead of frame-size increases"],"tags":["cassandra","configuration","cql","native-protocol"],"backgroundTag":"value-out-of-range","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"}