apache/pulsar · error · IllegalArgumentException

Configuration field 'transactionPendingAckBatchedWriteMaxSiz

Error message

Configuration field 'transactionPendingAckBatchedWriteMaxSize' value must be greater than or equal to 128k

What it means

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.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/validator/TransactionBatchedWriteValidator.java:32

 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.pulsar.broker.validator;

import org.apache.pulsar.broker.ServiceConfiguration;

public class TransactionBatchedWriteValidator {

    public static void validate(ServiceConfiguration configuration){
        if (configuration.isTransactionPendingAckBatchedWriteEnabled()){
            if (configuration.getTransactionPendingAckBatchedWriteMaxRecords() < 10){
                throw new IllegalArgumentException("Configuration field "
                        + "'transactionPendingAckBatchedWriteMaxRecords' value must be greater than or equal to 10");
            }
            if (configuration.getTransactionPendingAckBatchedWriteMaxSize() < 1024 * 128){
                throw new IllegalArgumentException("Configuration field "
                        + "'transactionPendingAckBatchedWriteMaxSize' value must be greater than or equal to 128k");
            }
            if (configuration.getTransactionPendingAckBatchedWriteMaxDelayInMillis() < 1){
                throw new IllegalArgumentException("Configuration field "
                        + "'transactionPendingAckBatchedWriteMaxDelayInMillis' value must be greater than or equal to"
                        + " 1");
            }
        }
        if (configuration.isTransactionLogBatchedWriteEnabled()){
            if (configuration.getTransactionLogBatchedWriteMaxRecords() < 10){
                throw new IllegalArgumentException("Configuration field "
                        + "'transactionLogBatchedWriteMaxRecords' value must be greater than or equal to 10");
            }
            if (configuration.getTransactionLogBatchedWriteMaxSize() < 1024 * 128){
                throw new IllegalArgumentException("Configuration field "
                        + "'transactionLogBatchedWriteMaxSize' value must be greater than or equal to 128k");
            }
            if (configuration.getTransactionLogBatchedWriteMaxDelayInMillis() < 1){

View on GitHub (pinned to 820761864e)

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

Example fix

// before (broker.conf)
transactionPendingAckBatchedWriteEnabled=true
transactionPendingAckBatchedWriteMaxSize=65536
// after
transactionPendingAckBatchedWriteEnabled=true
transactionPendingAckBatchedWriteMaxSize=131072

Defensive patterns

Strategy: validation

Validate before calling

public static void checkPendingAckBatchedWriteMaxSize(ServiceConfiguration conf) {
    if (conf.isTransactionPendingAckBatchedWriteEnabled()
            && conf.getTransactionPendingAckBatchedWriteMaxSize() < 1024 * 128) {
        throw new IllegalArgumentException(
            "transactionPendingAckBatchedWriteMaxSize must be >= 131072 bytes (128k)");
    }
}
// Call TransactionBatchedWriteValidator.validate(config) at startup.

Try / catch

try {
    TransactionBatchedWriteValidator.validate(config);
} catch (IllegalArgumentException e) {
    log.fatal("Invalid transaction batched-write config: {}", e.getMessage());
    System.exit(1); // fail startup fast
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/defd98008f9cc37c. Report an issue: GitHub.