{"record":{"id":"bc38df610e7d6bb9","repo":"apache/cassandra","slug":"commitlog-segment-size-must-be-at-least-twice-the","errorCode":null,"errorMessage":"commitlog_segment_size must be at least twice the size of max_mutation_size / 1024","messagePattern":"commitlog_segment_size must be at least twice the size of max_mutation_size / 1024","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/DatabaseDescriptor.java","lineNumber":1132,"sourceCode":"\n        if (conf.allow_extra_insecure_udfs)\n            logger.warn(\"Allowing java.lang.System.* access in UDFs is dangerous and not recommended. Set allow_extra_insecure_udfs: false to disable.\");\n\n        if (conf.scripted_user_defined_functions_enabled)\n            throw new ConfigurationException(\"JavaScript user-defined functions were removed in CASSANDRA-18252. \" +\n                                             \"Hooks are planned to be introduced as part of CASSANDRA-17280\");\n\n        if (conf.commitlog_segment_size.toMebibytes() == 0)\n            throw new ConfigurationException(\"commitlog_segment_size must be positive, but was \"\n                                             + conf.commitlog_segment_size.toString(), false);\n        else if (conf.commitlog_segment_size.toMebibytes() >= 2048)\n            throw new ConfigurationException(\"commitlog_segment_size must be smaller than 2048, but was \"\n                                             + conf.commitlog_segment_size.toString(), false);\n\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","sourceCodeStart":1114,"sourceCodeEnd":1150,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/DatabaseDescriptor.java#L1114-L1150","documentation":"Thrown when commitlog_segment_size is less than twice max_mutation_size (both in KiB). A commit log segment must be able to hold at least two mutations of maximum size; the explicit max_mutation_size must therefore be at most half the segment size.","triggerScenarios":"cassandra.yaml sets max_mutation_size explicitly such that 2 * max_mutation_size > commitlog_segment_size, e.g. segment 32MiB with max_mutation_size 20MiB. This branch runs only when max_mutation_size is non-null (explicitly configured).","commonSituations":"Operators raising max_mutation_size for large batches without proportionally raising commitlog_segment_size; copying segment-size defaults from a different config where max_mutation_size was tuned.","solutions":["Raise commitlog_segment_size to at least 2x max_mutation_size, or","lower max_mutation_size to <= commitlog_segment_size / 2, or","remove max_mutation_size so it defaults to commitlog_segment_size / 2.","Restart the node."],"exampleFix":"// before (yaml)\ncommitlog_segment_size: 32MiB\nmax_mutation_size: 20MiB\n// after\ncommitlog_segment_size: 64MiB\nmax_mutation_size: 20MiB","handlingStrategy":"validation","validationCode":"Long segKiB = parseKibibytes(yaml.get(\"commitlog_segment_size\"));\nLong mutKiB = parseKibibytes(yaml.get(\"max_mutation_size\"));\nif (segKiB != null && mutKiB != null && segKiB < 2 * mutKiB)\n    throw new IllegalArgumentException(\"commitlog_segment_size must be >= 2 * max_mutation_size\");","typeGuard":null,"tryCatchPattern":"try {\n    DatabaseDescriptor.applySimpleConfig();\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"twice the size of max_mutation_size\"))\n        logger.error(\"Raise commitlog_segment_size to >= 2x max_mutation_size\");\n}","preventionTips":["Avoid setting max_mutation_size explicitly; it defaults to segment/2","If raising max_mutation_size, raise segment size to at least 2x in the same change","Model the two values as one ratio in config tooling"],"tags":["config","commitlog"],"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-17T15:17:12.973Z"}