{"record":{"id":"7095276ffefb92c2","repo":"apache/rocketmq","slug":"popinvisibletime-out-of-range-min-max","errorCode":null,"errorMessage":"popInvisibleTime Out of range [{min}, {max}]","messagePattern":"popInvisibleTime Out of range \\[(.+?), (.+?)\\]","errorType":"validation","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1197,"sourceCode":"            || this.defaultMQPushConsumer.getConsumeMessageBatchMaxSize() > 1024) {\n            throw new MQClientException(\n                \"consumeMessageBatchMaxSize Out of range [1, 1024]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // pullBatchSize\n        if (this.defaultMQPushConsumer.getPullBatchSize() < 1 || this.defaultMQPushConsumer.getPullBatchSize() > 1024) {\n            throw new MQClientException(\n                \"pullBatchSize Out of range [1, 1024]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // popInvisibleTime\n        if (this.defaultMQPushConsumer.getPopInvisibleTime() < MIN_POP_INVISIBLE_TIME\n            || this.defaultMQPushConsumer.getPopInvisibleTime() > MAX_POP_INVISIBLE_TIME) {\n            throw new MQClientException(\n                \"popInvisibleTime Out of range [\" + MIN_POP_INVISIBLE_TIME + \", \" + MAX_POP_INVISIBLE_TIME + \"]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // popBatchNums\n        if (this.defaultMQPushConsumer.getPopBatchNums() <= 0 || this.defaultMQPushConsumer.getPopBatchNums() > 32) {\n            throw new MQClientException(\n                \"popBatchNums Out of range [1, 32]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n    }\n\n    private void copySubscription() throws MQClientException {\n        try {\n            Map<String, String> sub = this.defaultMQPushConsumer.getSubscription();\n            if (sub != null) {","sourceCodeStart":1179,"sourceCodeEnd":1215,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1179-L1215","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set popInvisibleTime between 5000 and 300000 ms (default 60000)","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","For long business tasks, extend the consumer's ack/redelivery strategy rather than raising the value above the 5-minute cap"],"exampleFix":"// before\nconsumer.setPopInvisibleTime(3_000); // 3 s: below the 5 s minimum\n// after\nconsumer.setPopInvisibleTime(60_000); // 60 s, in range; covers slow processing + margin","handlingStrategy":"validation","validationCode":"long v = consumer.getPopInvisibleTime();\nif (v < 5000 || v > 300000) throw new IllegalArgumentException(\"popInvisibleTime must be [5000,300000] ms: \" + v);\nconsumer.start();","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getMessage().contains(\"popInvisibleTime\")) throw new ConfigException(e); throw e; }","preventionTips":["Budget popInvisibleTime = worst-case processing time + margin to avoid double delivery","Remember the floor is 5 s even if another MQ allowed less","Build the value via TimeUnit.MILLISECONDS"],"tags":["rocketmq","consumer","pop-consumption","configuration","validation"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}