apache/rocketmq · error · MQClientException

pullThresholdForQueue Out of range [1, 65535]

Error message

pullThresholdForQueue Out of range [1, 65535]

What it means

checkConfig() validates pullThresholdForQueue — the per-queue limit of locally cached (not yet consumed) messages that triggers pull flow control — which must be in [1, 65535]. Default is 1000, so the error implies an explicit out-of-range value.

Source

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

        if (this.defaultMQPushConsumer.getConsumeThreadMin() > this.defaultMQPushConsumer.getConsumeThreadMax()) {
            throw new MQClientException(
                "consumeThreadMin (" + this.defaultMQPushConsumer.getConsumeThreadMin() + ") "
                    + "is larger than consumeThreadMax (" + this.defaultMQPushConsumer.getConsumeThreadMax() + ")",
                null);
        }

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

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

        // pullThresholdForTopic
        if (this.defaultMQPushConsumer.getPullThresholdForTopic() != -1) {
            if (this.defaultMQPushConsumer.getPullThresholdForTopic() < 1 || this.defaultMQPushConsumer.getPullThresholdForTopic() > 6553500) {
                throw new MQClientException(
                    "pullThresholdForTopic Out of range [1, 6553500]"
                        + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                    null);
            }
        }

        // pullThresholdSizeForQueue
        if (this.defaultMQPushConsumer.getPullThresholdSizeForQueue() < 1 || this.defaultMQPushConsumer.getPullThresholdSizeForQueue() > 1024) {
            throw new MQClientException(

View on GitHub (pinned to 293f588571)

Solutions

1. Keep pullThresholdForQueue in [1,65535]; default 1000, raise to e.g. 5000 if pull flow control logs appear
2. To disable per-queue count flow control in newer versions, use pullThresholdForTopic=-1 semantics carefully instead of 0 on the queue field
3. Check the sibling field: pullThresholdSizeForQueue (MiB, [1,1024]) is a separate knob often confused with this one

Example fix

// before
consumer.setPullThresholdForQueue(0); // meant 'unlimited'

// after
consumer.setPullThresholdForQueue(1000); // default; raise within [1,65535] as needed

int t = config.getPullThresholdForQueue();
if (t < 1 || t > 65535) throw new IllegalArgumentException("pullThresholdForQueue must be in [1,65535]: " + t);
consumer.setPullThresholdForQueue(t);

boolean inQueueThresholdRange(int v) { return v >= 1 && v <= 65535; }

When it happens

Trigger: setPullThresholdForQueue(0) (intending 'no limit'), a negative value, or >65535; unit confusion with pullThresholdSizeForQueue (which is in MiB and capped at 1024).

Common situations: Attempting to disable message-count flow control for fast consumers; copying memory-based thresholds (e.g. 100000) into the count-based field.

Related errors

• consumeConcurrentlyMaxSpan Out of range [1, 65535]
• pullThresholdForTopic Out of range [1, 6553500]
• consumerGroup can not equal
• consumerGroup is null
• messageModel is null

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