apache/rocketmq · error · MQClientException

pullInterval Out of range [0, 65535]

Error message

pullInterval Out of range [0, 65535]

What it means

Thrown during push-consumer startup when pullInterval is outside [0, 65535] milliseconds. pullInterval is the delay between two consecutive pull requests on a queue, used to slow down consumption (application-level throttling). Zero means pull as fast as possible; the client rejects negative delays and anything above ~65 s because scheduling with such values is not meaningful.

Source

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

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

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

        // pullBatchSize
        if (this.defaultMQPushConsumer.getPullBatchSize() < 1 || this.defaultMQPushConsumer.getPullBatchSize() > 1024) {
            throw new MQClientException(
                "pullBatchSize Out of range [1, 1024]"

View on GitHub (pinned to 293f588571)

Solutions

1. Set pullInterval to a millisecond value in [0, 65535] (default 0)
2. Verify the time unit at the call site and convert explicitly, e.g. TimeUnit.SECONDS.toMillis(10)
3. For aggressive throttling, use a rate limiter inside the MessageListener instead of a large pullInterval

Example fix

// before
consumer.setPullInterval(10); // meant 10 seconds? no — 10 ms; or
consumer.setPullInterval(60_000_000); // out of range
// after
consumer.setPullInterval(TimeUnit.SECONDS.toMillis(1)); // 1000 ms, in range

long v = consumer.getPullInterval();
if (v < 0 || v > 65535) throw new IllegalArgumentException("pullInterval must be [0,65535] ms: " + v);
consumer.start();

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

When it happens

Trigger: Calling consumer.setPullInterval(n) with n < 0 or n > 65535, then consumer.start(). Most commonly n was specified in the wrong time unit (seconds or microseconds handed to a millisecond API).

Common situations: Passing seconds where milliseconds are expected (e.g. 10 intended as 10 s but 10_000_000 ms given, exceeding 65535); attempting to slow consumption drastically via a huge interval instead of using a RateLimiter in the listener; YAML/properties value parsed as nanoseconds by a framework.

Related errors

• pullThresholdSizeForQueue Out of range [1, 1024]
• pullThresholdSizeForTopic Out of range [1, 102400]
• 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/e9b564ee24751e3f. Report an issue: GitHub.