apache/pulsar · error · IllegalArgumentException

'transactionLogBatchedWriteMaxRecords' value must be greater

Error message

'transactionLogBatchedWriteMaxRecords' value must be greater than or equal to 10

What it means

When transactionLogBatchedWriteEnabled=true, the validator requires transactionLogBatchedWriteMaxRecords to be at least 10. Values below 10 would create transaction-log batches too small to be useful, so the broker throws IllegalArgumentException at configuration validation time.

Source

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

    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

1. Set transactionLogBatchedWriteMaxRecords to at least 10 in broker.conf (e.g. 100-500 for typical workloads)
2. Audit config-generation tooling to clamp the value to >= 10
3. If small batches are truly desired, disable transactionLogBatchedWriteEnabled instead of lowering the record count below the floor

Example fix

// before (broker.conf)
transactionLogBatchedWriteEnabled=true
transactionLogBatchedWriteMaxRecords=5
// after
transactionLogBatchedWriteEnabled=true
transactionLogBatchedWriteMaxRecords=100

int maxRecords = config.getTransactionLogBatchedWriteMaxRecords();
if (config.isTransactionLogBatchedWriteEnabled() && maxRecords < 10) {
    throw new IllegalArgumentException("transactionLogBatchedWriteMaxRecords must be >= 10, got " + maxRecords);
}

When it happens

Trigger: Broker startup/config reload with transactionLogBatchedWriteEnabled=true and transactionLogBatchedWriteMaxRecords < 10 (e.g. set to 1 or 5 to 'reduce batching').

Common situations: Tuning attempts that lower max records for lower latency; configs copied from examples with disabled batching then only the enable flag flipped; migration scripts applying conservative values.

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

• Configuration field 'transactionPendingAckBatchedWriteMaxDel
• 'transactionLogBatchedWriteMaxSize' value must be greater th
• 'transactionLogBatchedWriteMaxDelayInMillis' value must be g
• there are redundant configure for listener `${listenerName}`
• must not specify `${hostPort}` to different listener.

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