apache/rocketmq · error · MQClientException

pullThresholdSizeForTopic Out of range [1, 102400]

Error message

pullThresholdSizeForTopic Out of range [1, 102400]

What it means

Thrown during push-consumer startup when pullThresholdSizeForTopic is set to a value outside [1, 102400] (MiB). This is the topic-level back-pressure limit on total estimated unread message size across all queues of a topic. It is only validated when the value differs from the -1 sentinel, i.e. once you opt in the value must be in range.

Source

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

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

View on GitHub (pinned to 293f588571)

Solutions

1. Set the value in [1, 102400] MiB, or leave it unset (-1) if you only want per-queue limiting
2. Ensure pullThresholdSizeForTopic >= pullThresholdSizeForQueue * (expected queue count) so topic-level throttling does not strangle per-queue flow
3. Double-check the unit: the setter takes MiB, so remove any bytes-to-MiB conversion mistakes

Example fix

// before
consumer.setPullThresholdSizeForTopic(500 * 1024 * 1024); // treated as MiB, out of range
// after
consumer.setPullThresholdSizeForTopic(10 * 1024); // 10240 MiB at topic level
// or simply omit the setter to keep the -1 default

int v = consumer.getPullThresholdSizeForTopic();
if (v != -1 && (v < 1 || v > 102400)) throw new IllegalArgumentException("pullThresholdSizeForTopic must be -1 or in [1,102400] MiB: " + v);
consumer.start();

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

When it happens

Trigger: Calling consumer.setPullThresholdSizeForTopic(n) with n < 1 or n > 102400 and then consumer.start(). Leaving it at the default -1 never triggers this error.

Common situations: Setting the topic threshold below the per-queue threshold causing inconsistent flow control; copying broker-side limits (e.g. 1024000) into the client property; unit-to-unit confusion — the value is MiB, not bytes or KiB.

Related errors

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