apache/rocketmq · error · MQClientException

consumeConcurrentlyMaxSpan Out of range [1, 65535]

Error message

consumeConcurrentlyMaxSpan Out of range [1, 65535]

What it means

checkConfig() validates consumeConcurrentlyMaxSpan — the maximum difference (in messages) allowed between the first and last message queued for a queue before flow-controlling pulls — which must be in [1, 65535]. Default is 2000, so an out-of-range value was explicitly set.

Source

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

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

        // consumeThreadMin can't be larger than consumeThreadMax
        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]"

View on GitHub (pinned to 293f588571)

Solutions

1. Keep the value in [1,65535]; the default 2000 suits most consumers
2. To relax flow control, raise it moderately (e.g. 4096) rather than disabling it
3. If slow consumption triggers flow control, tune consumeThreadMin/Max and the consumer logic before raising the span

Example fix

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

// after
consumer.setConsumeConcurrentlyMaxSpan(2000); // default, or up to 65535

int span = config.getConsumeConcurrentlyMaxSpan();
if (span < 1 || span > 65535) throw new IllegalArgumentException("consumeConcurrentlyMaxSpan must be in [1,65535]: " + span);
consumer.setConsumeConcurrentlyMaxSpan(span);

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

When it happens

Trigger: setConsumeConcurrentlyMaxSpan(0) or a value above 65535; large values copied from memory-size tuning with a wrong unit; -1 sentinels from 'unlimited' conventions.

Common situations: Trying to disable span-based flow control by setting 0 or a huge number; config generation templates defaulting numeric fields to 0.

Related errors

• pullThresholdForQueue 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/3a0c9d661d878096. Report an issue: GitHub.