apache/rocketmq · error · MQClientException

consumeMessageBatchMaxSize Out of range [1, 1024]

Error message

consumeMessageBatchMaxSize Out of range [1, 1024]

What it means

Thrown during push-consumer startup when consumeMessageBatchMaxSize is outside [1, 1024]. This is the maximum number of messages passed to a single MessageListenerConcurrently.onMessage(List) invocation when the batch listener interface is used. The lower bound of 1 exists because at least one message per call is required, and the upper bound caps the batch to protect heap and acknowledgment granularity.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java:1180

                throw new MQClientException(
                    "pullThresholdSizeForTopic Out of range [1, 102400]"
                        + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                    null);
            }
        }

        // pullInterval
        if (this.defaultMQPushConsumer.getPullInterval() < 0 || this.defaultMQPushConsumer.getPullInterval() > 65535) {
            throw new MQClientException(
                "pullInterval Out of range [0, 65535]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // consumeMessageBatchMaxSize
        if (this.defaultMQPushConsumer.getConsumeMessageBatchMaxSize() < 1
            || this.defaultMQPushConsumer.getConsumeMessageBatchMaxSize() > 1024) {
            throw new MQClientException(
                "consumeMessageBatchMaxSize Out of range [1, 1024]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // pullBatchSize
        if (this.defaultMQPushConsumer.getPullBatchSize() < 1 || this.defaultMQPushConsumer.getPullBatchSize() > 1024) {
            throw new MQClientException(
                "pullBatchSize Out of range [1, 1024]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // popInvisibleTime
        if (this.defaultMQPushConsumer.getPopInvisibleTime() < MIN_POP_INVISIBLE_TIME
            || this.defaultMQPushConsumer.getPopInvisibleTime() > MAX_POP_INVISIBLE_TIME) {
            throw new MQClientException(
                "popInvisibleTime Out of range [" + MIN_POP_INVISIBLE_TIME + ", " + MAX_POP_INVISIBLE_TIME + "]"

View on GitHub (pinned to 293f588571)

Solutions

1. Set consumeMessageBatchMaxSize to a value in [1, 1024] (default 1)
2. Keep consumeMessageBatchMaxSize <= pullBatchSize, otherwise pulls limit the effective consume batch anyway
3. For throughput tuning, raise both pullBatchSize and consumeMessageBatchMaxSize together in moderate steps

Example fix

// before
consumer.setConsumeMessageBatchMaxSize(0); // invalid: minimum is 1
// after
consumer.setConsumeMessageBatchMaxSize(16); // batch of 16 per listener call
consumer.setPullBatchSize(32); // keep >= consume batch

int v = consumer.getConsumeMessageBatchMaxSize();
if (v < 1 || v > 1024) throw new IllegalArgumentException("consumeMessageBatchMaxSize must be in [1,1024]: " + v);
if (v > consumer.getPullBatchSize()) log.warn("consume batch > pull batch; effective batch capped by pullBatchSize");
consumer.start();

catch (MQClientException e) { if (e.getMessage().contains("consumeMessageBatchMaxSize")) throw new ConfigException(e); throw e; }

When it happens

Trigger: Calling consumer.setConsumeMessageBatchMaxSize(n) with n < 1 or n > 1024 followed by consumer.start(). Only relevant when the consumer was created with a List-based (batch) message listener, but the validation runs for all push consumers.

Common situations: Setting 0 thinking it disables batching (it does not — it breaks the contract); raising the batch size far beyond pullBatchSize, which wastes the setting since a consume batch can never exceed what was pulled; copy-paste of pullBatchSize tuning into the consume field.

Related errors

• pullBatchSize Out of range [1, 1024]
• pullThresholdSizeForQueue Out of range [1, 1024]
• pullThresholdSizeForTopic Out of range [1, 102400]
• pullInterval Out of range [0, 65535]
• popInvisibleTime Out of range [{min}, {max}]

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/53ecdc9b3289eebe. Report an issue: GitHub.