apache/pulsar · error · IllegalArgumentException

'transactionLogBatchedWriteMaxSize' value must be greater th

Error message

'transactionLogBatchedWriteMaxSize' value must be greater than or equal to 128k

What it means

When transactionLogBatchedWriteEnabled=true, transactionLogBatchedWriteMaxSize must be at least 128k (131072 bytes). The validator rejects smaller sizes with IllegalArgumentException to guarantee transaction log batches have a meaningful size floor.

Source

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

                        + "'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 transactionLogBatchedWriteMaxSize to 131072 or more (bytes) in broker.conf
Double-check the units: this field is in bytes, not KB/MB
If lowering memory usage is the goal, keep the 128k floor and tune maxRecords/maxDelay instead

Example fix

// before (broker.conf)
transactionLogBatchedWriteEnabled=true
transactionLogBatchedWriteMaxSize=65536
// after
transactionLogBatchedWriteEnabled=true
transactionLogBatchedWriteMaxSize=131072

Defensive patterns

Strategy: validation

Validate before calling

int maxSize = config.getTransactionLogBatchedWriteMaxSize();
if (config.isTransactionLogBatchedWriteEnabled() && maxSize < 1024 * 128) {
    throw new IllegalArgumentException("transactionLogBatchedWriteMaxSize must be >= 131072 bytes, got " + maxSize);
}

Prevention

Always express this field in bytes; annotate configs with the unit
Use constants (e.g. 128 * 1024) in automation instead of raw suspicious values
Validate config before deploy in CI

When it happens

Trigger: Broker startup/config reload with transactionLogBatchedWriteEnabled=true and transactionLogBatchedWriteMaxSize < 131072 (e.g. set in bytes as 1024 or mistakenly in KB).

Common situations: Units confusion — operators enter a KB value where bytes are expected; attempts to minimize memory footprint; configs ported from other systems' batch-size conventions.

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