apache/rocketmq · error · MQClientException

pullThresholdSizeForQueue Out of range [1, 1024]

Error message

pullThresholdSizeForQueue Out of range [1, 1024]

What it means

Thrown during DefaultMQPushConsumer startup (checkClientInBroker / checkConfig) when pullThresholdSizeForQueue is outside [1, 1024]. This is the per-queue flow-control threshold in MiB: when the estimated unread message size for a queue exceeds it, pulling is paused. The client validates configuration eagerly so an invalid flow-control value fails fast instead of causing unbounded memory growth.

Source

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

            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(
                "pullThresholdSizeForQueue Out of range [1, 1024]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        if (this.defaultMQPushConsumer.getPullThresholdSizeForTopic() != -1) {
            // pullThresholdSizeForTopic
            if (this.defaultMQPushConsumer.getPullThresholdSizeForTopic() < 1 || this.defaultMQPushConsumer.getPullThresholdSizeForTopic() > 102400) {
                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(

View on GitHub (pinned to 293f588571)

Solutions

1. Set pullThresholdSizeForQueue to a value in [1, 1024] (default is 100 MiB), e.g. consumer.setPullThresholdSizeForQueue(100);
2. If you meant to disable per-queue limiting in favor of topic-level limiting, keep this field in range and instead set pullThresholdSizeForTopic (which accepts -1 to stay inactive)
3. If you truly need >1024 MiB per queue, raise pullThresholdSizeForTopic instead and split queues across more consumers

Example fix

// before
consumer.setPullThresholdSizeForQueue(2048); // MiB, > 1024
consumer.start();
// after
consumer.setPullThresholdSizeForQueue(1024); // max allowed per queue
consumer.setPullThresholdSizeForTopic(10240); // tune at topic level if more headroom needed
consumer.start();

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

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

When it happens

Trigger: Calling consumer.start() (or producer/consumer factory start that runs checkConfig) with defaultMQPushConsumer.setPullThresholdSizeForQueue(n) where n < 1 or n > 1024. Note that, unlike pullThresholdSizeForTopic, this check is unconditional — there is no -1 sentinel to skip it.

Common situations: Copying a config template tuned for a very large heap and setting a value above 1024 MiB per queue; setting 0 or a negative number intending to 'disable' the limit (the API has no disable sentinel for this field); property-file typos that parse to 0.

Related errors

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

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