apache/rocketmq · error · MQClientException

pullBatchSize Out of range [1, 1024]

Error message

pullBatchSize Out of range [1, 1024]

What it means

Thrown during push-consumer startup when pullBatchSize is outside [1, 1024]. This is the maximum number of messages the client requests from the broker in a single pull call. Values below 1 cannot fetch anything and values above 1024 exceed the broker-side pull limit, so the client rejects them eagerly.

Source

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

        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 + "]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // popBatchNums
        if (this.defaultMQPushConsumer.getPopBatchNums() <= 0 || this.defaultMQPushConsumer.getPopBatchNums() > 32) {
            throw new MQClientException(
                "popBatchNums Out of range [1, 32]"

View on GitHub (pinned to 293f588571)

Solutions

1. Set pullBatchSize in [1, 1024] (default 32)
2. For large messages, lower pullBatchSize and consider pullThresholdSizeForQueue so size-based flow control kicks in before heap pressure
3. If more throughput is needed, scale with more queue/consumer instances instead of an oversized pull batch

Example fix

// before
consumer.setPullBatchSize(5000); // > 1024
// after
consumer.setPullBatchSize(256); // in range; tune upward only with measured heap headroom

int v = consumer.getPullBatchSize();
if (v < 1 || v > 1024) throw new IllegalArgumentException("pullBatchSize must be in [1,1024]: " + v);
consumer.start();

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

When it happens

Trigger: Calling consumer.setPullBatchSize(n) with n < 1 or n > 1024, then consumer.start(). Independent of consumeMessageBatchMaxSize, but interacts with it.

Common situations: Setting 0 or a negative number by mistake in a property file; pushing the value above 1024 while tuning for very large messages — which anyway causes oversized requests that the broker would reject; forgetting that a big pullBatchSize with large messages can exceed consumer memory even when below 1024.

Related errors

• consumeMessageBatchMaxSize 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/af0430e79a4117db. Report an issue: GitHub.