apache/rocketmq · error · MQClientException

popInvisibleTime Out of range [{min}, {max}]

Error message

popInvisibleTime Out of range [{min}, {max}]

What it means

Thrown during push-consumer startup when popInvisibleTime is outside [5000, 300000] ms (5 s to 5 min). popInvisibleTime only applies to POP consumption mode (a lightweight, queue-position-free consumption protocol) and defines how long a popped message stays invisible before it becomes redeliverable. The bounds prevent both tight redelivery loops (< 5 s) and effectively-lost messages stuck invisible for too long (> 5 min).

Source

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

            || 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]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // popInvisibleTime
        if (this.defaultMQPushConsumer.getPopInvisibleTime() < MIN_POP_INVISIBLE_TIME
            || this.defaultMQPushConsumer.getPopInvisibleTime() > MAX_POP_INVISIBLE_TIME) {
            throw new MQClientException(
                "popInvisibleTime Out of range [" + MIN_POP_INVISIBLE_TIME + ", " + MAX_POP_INVISIBLE_TIME + "]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // popBatchNums
        if (this.defaultMQPushConsumer.getPopBatchNums() <= 0 || this.defaultMQPushConsumer.getPopBatchNums() > 32) {
            throw new MQClientException(
                "popBatchNums Out of range [1, 32]"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }
    }

    private void copySubscription() throws MQClientException {
        try {
            Map<String, String> sub = this.defaultMQPushConsumer.getSubscription();
            if (sub != null) {

View on GitHub (pinned to 293f588571)

Solutions

1. Set popInvisibleTime between 5000 and 300000 ms (default 60000)
2. Size it to worst-case processing time plus margin, since a message that exceeds the invisible time will be redelivered while the first copy is still being processed
3. For long business tasks, extend the consumer's ack/redelivery strategy rather than raising the value above the 5-minute cap

Example fix

// before
consumer.setPopInvisibleTime(3_000); // 3 s: below the 5 s minimum
// after
consumer.setPopInvisibleTime(60_000); // 60 s, in range; covers slow processing + margin

long v = consumer.getPopInvisibleTime();
if (v < 5000 || v > 300000) throw new IllegalArgumentException("popInvisibleTime must be [5000,300000] ms: " + v);
consumer.start();

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

When it happens

Trigger: Calling consumer.setPopInvisibleTime(n) with n < 5000 or n > 300000 and then consumer.start(). The constants MIN_POP_INVISIBLE_TIME=5000 and MAX_POP_INVISIBLE_TIME=300000 are private in DefaultMQPushConsumerImpl (lines 138-139), so the range is fixed.

Common situations: Setting the invisible time equal to the expected business processing time without accounting for retries; unit mistakes (seconds passed to a millisecond setter); trying to emulate a very short visibility timeout like other MQ systems (SQS-style) where RocketMQ floors at 5 s.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• popBatchNums Out of range [1, 32]
• pullThresholdSizeForQueue Out of range [1, 1024]
• pullThresholdSizeForTopic Out of range [1, 102400]
• pullInterval Out of range [0, 65535]
• consumeMessageBatchMaxSize Out of range [1, 1024]

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