{"record":{"id":"0631b146765c0978","repo":"apache/rocketmq","slug":"popbatchnums-out-of-range-1-32","errorCode":null,"errorMessage":"popBatchNums Out of range [1, 32]","messagePattern":"popBatchNums Out of range \\[1, 32\\]","errorType":"validation","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1205,"sourceCode":"        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) {\n                for (final Map.Entry<String, String> entry : sub.entrySet()) {\n                    final String topic = entry.getKey();\n                    final String subString = entry.getValue();\n                    SubscriptionData subscriptionData = FilterAPI.buildSubscriptionData(topic, subString);\n                    this.rebalanceImpl.getSubscriptionInner().put(topic, subscriptionData);\n                }\n            }\n","sourceCodeStart":1187,"sourceCodeEnd":1223,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1187-L1223","documentation":"Thrown during push-consumer startup when popBatchNums is outside [1, 32]. popBatchNums controls how many messages the broker returns per POP request in POP consumption mode. The upper bound of 32 matches broker-side POP limits, and at least one message per pop is required.","triggerScenarios":"Calling consumer.setPopBatchNums(n) with n <= 0 or n > 32, then consumer.start(). Only meaningful when the consumer actually runs in POP mode (e.g. a Lite consumer / assign mode), but the check runs for every push consumer start.","commonSituations":"Tuning popBatchNums above 32 while chasing throughput; leaving an unset numeric field that deserializes to 0 from a config source; confusing popBatchNums with pullBatchSize (max 1024) and copying a value between them.","solutions":["Set popBatchNums to a value in [1, 32] (default 32 is not configurable beyond this)","Keep popBatchNums aligned with the listener's processing capacity so popped messages do not time out invisibility","For more POP throughput, increase consumer concurrency or use more consumers rather than exceeding 32"],"exampleFix":"// before\nconsumer.setPopBatchNums(64); // > 32, rejected at start()\n// after\nconsumer.setPopBatchNums(32); // maximum allowed per pop request","handlingStrategy":"validation","validationCode":"int v = consumer.getPopBatchNums();\nif (v < 1 || v > 32) throw new IllegalArgumentException(\"popBatchNums must be in [1,32]: \" + v);\nconsumer.start();","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getMessage().contains(\"popBatchNums\")) throw new ConfigException(e); throw e; }","preventionTips":["Never copy pullBatchSize (max 1024) into popBatchNums (max 32)","Scale POP throughput with concurrency/consumer count, not batch size"],"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"}