apache/pulsar · error · IllegalArgumentException

'transactionLogBatchedWriteMaxDelayInMillis' value must be g

Error message

'transactionLogBatchedWriteMaxDelayInMillis' value must be greater than or equal to 1

What it means

When transactionLogBatchedWriteEnabled=true, transactionLogBatchedWriteMaxDelayInMillis must be >= 1. A value of 0 or negative is rejected with IllegalArgumentException by TransactionBatchedWriteValidator before the broker can start with batched transaction-log writes.

Source

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

                        + "'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 transactionLogBatchedWriteMaxDelayInMillis=1 or higher in broker.conf
Set all sibling fields together: maxRecords >= 10, maxSize >= 131072, maxDelayInMillis >= 1
Validate the generated broker.conf in CI before deploying

Example fix

// before (broker.conf)
transactionLogBatchedWriteEnabled=true
transactionLogBatchedWriteMaxDelayInMillis=0
// after
transactionLogBatchedWriteEnabled=true
transactionLogBatchedWriteMaxDelayInMillis=5

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Never ship 0 for this field when batching is enabled; use 1 ms as the minimum
Bundle all four transaction batched-write fields in one validated config block
Test broker startup with the final generated broker.conf before rollout

When it happens

Trigger: Broker startup/config reload with transactionLogBatchedWriteEnabled=true and transactionLogBatchedWriteMaxDelayInMillis=0 (often the untouched default) or negative.

Common situations: Enabling batching while leaving delay at its 0 default; templated configs that only set the enable flag; assuming 0 means 'flush immediately' when the validator requires at least 1 ms.

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/fcc50ad317a1e6ec. Report an issue: GitHub.