apache/rocketmq · error · MQClientException

pullThresholdForTopic Out of range [1, 6553500]

Error message

pullThresholdForTopic Out of range [1, 6553500]

What it means

checkConfig() validates pullThresholdForTopic — the topic-level total cap on cached messages across all queues that triggers flow control. The sentinel -1 means 'disabled/not set'; any other value must lie in [1, 6553500]. The error fires when a non-sentinel value falls outside that band.

Source

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

            || 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(
                "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(

View on GitHub (pinned to 293f588571)

Solutions

1. Use -1 to disable the topic-level threshold, or set a value in [1,6553500]
2. Rule of thumb: set it to roughly (number of queues) * pullThresholdForQueue
3. Validate at config load that the field is -1 or within range so misconfigurations surface before start()

Example fix

// before
consumer.setPullThresholdForTopic(0); // invalid; 0 is not the disable sentinel

// after
consumer.setPullThresholdForTopic(-1); // disabled, or e.g. 100000 within range

int t = config.getPullThresholdForTopic();
if (t != -1 && (t < 1 || t > 6553500))
    throw new IllegalArgumentException("pullThresholdForTopic must be -1 or in [1,6553500]: " + t);
consumer.setPullThresholdForTopic(t);

boolean validTopicThreshold(int v) { return v == -1 || (v >= 1 && v <= 6553500); }

When it happens

Trigger: setPullThresholdForTopic(0) intending to disable (0 is invalid; only -1 disables); values above 6,553,500; inheriting 0 from a config default where the key was meant to stay unset.

Common situations: Config templates that default every numeric field to 0; migrating from per-queue to per-topic thresholds and using 0 as 'off'.

Related errors

• consumeConcurrentlyMaxSpan Out of range [1, 65535]
• pullThresholdForQueue Out of range [1, 65535]
• 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/b69d1dbf9a2ac0f1. Report an issue: GitHub.