apache/pulsar · error · IllegalArgumentException

Configuration field 'transactionPendingAckBatchedWriteMaxRec

Error message

Configuration field 'transactionPendingAckBatchedWriteMaxRecords' value must be greater than or equal to 10

What it means

TransactionBatchedWriteValidator.validate enforces startup configuration constraints for transaction pending-ack batched writes. When transactionPendingAckBatchedWriteEnabled is true, transactionPendingAckBatchedWriteMaxRecords must be at least 10; otherwise it throws IllegalArgumentException. This prevents configuring batches too small to be useful.

Source

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

 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "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){

View on GitHub (pinned to 820761864e)

Solutions

1. Set transactionPendingAckBatchedWriteMaxRecords to a value >= 10 (e.g. 500)
2. If you don't want batching constraints, set transactionPendingAckBatchedWriteEnabled=false
3. Check broker.conf / Kubernetes values.yaml for an overridden or empty value
4. Run ./gradlew sanityCheck or start with the validator locally to catch other related limits (maxSize >= 128k, maxDelay >= 1)

Example fix

// before (broker.conf)
transactionPendingAckBatchedWriteEnabled=true
transactionPendingAckBatchedWriteMaxRecords=5
// after
transactionPendingAckBatchedWriteEnabled=true
transactionPendingAckBatchedWriteMaxRecords=500

public static void checkPendingAckBatchedWriteConfig(ServiceConfiguration conf) {
    if (conf.isTransactionPendingAckBatchedWriteEnabled()
            && conf.getTransactionPendingAckBatchedWriteMaxRecords() < 10) {
        throw new IllegalArgumentException(
            "transactionPendingAckBatchedWriteMaxRecords must be >= 10 when batched write is enabled");
    }
}
// Call TransactionBatchedWriteValidator.validate(config) at startup before serving traffic.

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

When it happens

Trigger: Starting a broker with transactionPendingAckBatchedWriteEnabled=true and transactionPendingAckBatchedWriteMaxRecords set to a value < 10 (e.g. 1, 5, or unset/0).

Common situations: Enabling pending-ack batched writes in broker.conf/standalone.conf but copying a sample config with a small maxRecords value; typos leaving the value at 0; ops scripts templating the field incorrectly.

Related errors

• Configuration field 'transactionPendingAckBatchedWriteMaxSiz
• Timeout during delete operation
• Timeout during close operation
• Timeout during open-cursor operation
• Timeout during delete-cursors operation

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