{"record":{"id":"defd98008f9cc37c","repo":"apache/pulsar","slug":"configuration-field-transactionpendingackbatchedw-defd98","errorCode":null,"errorMessage":"Configuration field 'transactionPendingAckBatchedWriteMaxSize' value must be greater than or equal to 128k","messagePattern":"Configuration field 'transactionPendingAckBatchedWriteMaxSize' value must be greater than or equal to 128k","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/validator/TransactionBatchedWriteValidator.java","lineNumber":32,"sourceCode":" * \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n * KIND, either express or implied.  See the License for the\n * specific language governing permissions and limitations\n * under the License.\n */\npackage org.apache.pulsar.broker.validator;\n\nimport org.apache.pulsar.broker.ServiceConfiguration;\n\npublic class TransactionBatchedWriteValidator {\n\n    public static void validate(ServiceConfiguration configuration){\n        if (configuration.isTransactionPendingAckBatchedWriteEnabled()){\n            if (configuration.getTransactionPendingAckBatchedWriteMaxRecords() < 10){\n                throw new IllegalArgumentException(\"Configuration field \"\n                        + \"'transactionPendingAckBatchedWriteMaxRecords' value must be greater than or equal to 10\");\n            }\n            if (configuration.getTransactionPendingAckBatchedWriteMaxSize() < 1024 * 128){\n                throw new IllegalArgumentException(\"Configuration field \"\n                        + \"'transactionPendingAckBatchedWriteMaxSize' value must be greater than or equal to 128k\");\n            }\n            if (configuration.getTransactionPendingAckBatchedWriteMaxDelayInMillis() < 1){\n                throw new IllegalArgumentException(\"Configuration field \"\n                        + \"'transactionPendingAckBatchedWriteMaxDelayInMillis' value must be greater than or equal to\"\n                        + \" 1\");\n            }\n        }\n        if (configuration.isTransactionLogBatchedWriteEnabled()){\n            if (configuration.getTransactionLogBatchedWriteMaxRecords() < 10){\n                throw new IllegalArgumentException(\"Configuration field \"\n                        + \"'transactionLogBatchedWriteMaxRecords' value must be greater than or equal to 10\");\n            }\n            if (configuration.getTransactionLogBatchedWriteMaxSize() < 1024 * 128){\n                throw new IllegalArgumentException(\"Configuration field \"\n                        + \"'transactionLogBatchedWriteMaxSize' value must be greater than or equal to 128k\");\n            }\n            if (configuration.getTransactionLogBatchedWriteMaxDelayInMillis() < 1){","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/validator/TransactionBatchedWriteValidator.java#L14-L50","documentation":"TransactionBatchedWriteValidator.validate enforces startup configuration constraints for transaction pending-ack batched writes. When transactionPendingAckBatchedWriteEnabled is true, transactionPendingAckBatchedWriteMaxSize must be at least 128 KB (1024*128 bytes); otherwise it throws IllegalArgumentException. This prevents batched writes that are too small to amortize I/O.","triggerScenarios":"Starting a broker with transactionPendingAckBatchedWriteEnabled=true and transactionPendingAckBatchedWriteMaxSize set below 131072 bytes (e.g. 65536, or a small value entered in bytes thinking it was KB).","commonSituations":"Entering the value in KB or MB units while the config expects bytes; copying a low sample value; fine-tuning batch sizes downward past the floor to reduce latency.","solutions":["Set transactionPendingAckBatchedWriteMaxSize to >= 131072 (128k bytes), e.g. 1048576 (1MB)","Set transactionPendingAckBatchedWriteEnabled=false if batched pending-ack writes are not needed","Double-check units: the field is plain bytes, not KB/MB","Also validate the sibling limits: maxRecords >= 10 and maxDelayInMillis >= 1"],"exampleFix":"// before (broker.conf)\ntransactionPendingAckBatchedWriteEnabled=true\ntransactionPendingAckBatchedWriteMaxSize=65536\n// after\ntransactionPendingAckBatchedWriteEnabled=true\ntransactionPendingAckBatchedWriteMaxSize=131072","handlingStrategy":"validation","validationCode":"public static void checkPendingAckBatchedWriteMaxSize(ServiceConfiguration conf) {\n    if (conf.isTransactionPendingAckBatchedWriteEnabled()\n            && conf.getTransactionPendingAckBatchedWriteMaxSize() < 1024 * 128) {\n        throw new IllegalArgumentException(\n            \"transactionPendingAckBatchedWriteMaxSize must be >= 131072 bytes (128k)\");\n    }\n}\n// Call TransactionBatchedWriteValidator.validate(config) at startup.","typeGuard":null,"tryCatchPattern":"try {\n    TransactionBatchedWriteValidator.validate(config);\n} catch (IllegalArgumentException e) {\n    log.fatal(\"Invalid transaction batched-write config: {}\", e.getMessage());\n    System.exit(1); // fail startup fast\n}","preventionTips":["Remember the field is in raw bytes; 128k = 131072, not 128","Keep transactionPendingAckBatchedWriteMaxSize at or above 1MB for production workloads","Validate the full config with TransactionBatchedWriteValidator.validate() before deploying","When tuning for latency, stay above the 128k floor instead of disabling the floor"],"tags":["configuration","transaction","validation"],"backgroundTag":"invalid-broker-configuration","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}