apache/pulsar · error · IllegalArgumentException

Configuration field 'transactionPendingAckBatchedWriteMaxDel

Error message

Configuration field 'transactionPendingAckBatchedWriteMaxDelayInMillis' value must be greater than or equal to 1

What it means

The broker validates transaction-related broker.conf fields when batched writes for pending acknowledgments are enabled. If transactionPendingAckBatchedWriteEnabled=true but transactionPendingAckBatchedWriteMaxDelayInMillis is less than 1 (including the 0 default), TransactionBatchedWriteValidator.validate throws IllegalArgumentException during broker startup/configuration load, refusing to start with an invalid config.

Source

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

 */
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){
                throw new IllegalArgumentException("Configuration field "
                        + "'transactionLogBatchedWriteMaxDelayInMillis' value must be greater than or equal to 1");
            }
        }

View on GitHub (pinned to 820761864e)

Solutions

Set transactionPendingAckBatchedWriteMaxDelayInMillis=1 or higher in broker.conf (e.g. 1-10 ms is typical)
Ensure the value is an integer >= 1 wherever the config is generated/templated
Only enable transactionPendingAckBatchedWriteEnabled=true after setting all three related fields (maxSize >= 131072, maxDelayInMillis >= 1)
Restart/reload the broker and confirm startup succeeds

Example fix

// before (broker.conf)
transactionPendingAckBatchedWriteEnabled=true
transactionPendingAckBatchedWriteMaxSize=131072
transactionPendingAckBatchedWriteMaxDelayInMillis=0
// after
transactionPendingAckBatchedWriteEnabled=true
transactionPendingAckBatchedWriteMaxSize=131072
transactionPendingAckBatchedWriteMaxDelayInMillis=1

Defensive patterns

Strategy: validation

Validate before calling

int maxDelay = config.getTransactionPendingAckBatchedWriteMaxDelayInMillis();
if (config.isTransactionPendingAckBatchedWriteEnabled() && maxDelay < 1) {
    throw new IllegalArgumentException("transactionPendingAckBatchedWriteMaxDelayInMillis must be >= 1, got " + maxDelay);
}

Prevention

Set maxDelayInMillis together with the enable flag in every config template
Add a config lint/CI check asserting >= 1 for all transaction batched-write fields
Document units (millis) and floor (1) next to the field in deployment tooling

When it happens

Trigger: Starting or hot-reloading a broker with transactionPendingAckBatchedWriteEnabled=true and transactionPendingAckBatchedWriteMaxDelayInMillis set to 0 or a negative integer (often left at default 0 while only enabling batching and max size).

Common situations: Operators enable transaction pending-ack batching but forget the delay is 0 by default; copy-pasted configs omit the delay field; automation templates set delay=0 expecting 'no delay' semantics.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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