apache/rocketmq · error · MQClientException

consumeThreadMax Out of range [1, 1000]

Error message

consumeThreadMax Out of range [1, 1000]

What it means

checkConfig() validates the consume-thread pool's maximum thread count: it must be between 1 and 1000 inclusive. Default is 20 (or 65 in some versions), so this is always an explicitly misconfigured value.

Source

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

        if (!orderly && !concurrently) {
            throw new MQClientException(
                "messageListener must be instanceof MessageListenerOrderly or MessageListenerConcurrently"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

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

        // consumeThreadMax
        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]"

View on GitHub (pinned to 293f588571)

Solutions

1. Set consumeThreadMax within [1,1000]; size for your consumer latency (e.g. 20-200)
2. If throughput is insufficient at 1000 threads, the bottleneck is usually the consumer logic or downstream — parallelize there instead
3. Keep min <= max to avoid error 236

Example fix

// before
consumer.setConsumeThreadMax(2000); // over cap

// after
consumer.setConsumeThreadMax(200);

int max = config.getConsumeThreadMax();
if (max < 1 || max > 1000) throw new IllegalArgumentException("consumeThreadMax must be in [1,1000]: " + max);
consumer.setConsumeThreadMax(max);

boolean inThreadRange(int v) { return v >= 1 && v <= 1000; }

When it happens

Trigger: setConsumeThreadMax(0), a negative number, or >1000; copying a large 'maxThreads' value from an HTTP server pool config; unit mismatch (e.g. 5000 meant as a queue capacity).

Common situations: Porting Tomcat/Netty pool settings into RocketMQ consumer config; scaling thread counts for slow consumers and overshooting the hard cap.

Related errors

• consumeThreadMin Out of range [1, 1000]
• consumerGroup can not equal
• consumerGroup is null
• messageModel is null
• consumeFromWhere is null

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