{"record":{"id":"53ecdc9b3289eebe","repo":"apache/rocketmq","slug":"consumemessagebatchmaxsize-out-of-range-1-1024","errorCode":null,"errorMessage":"consumeMessageBatchMaxSize Out of range [1, 1024]","messagePattern":"consumeMessageBatchMaxSize Out of range \\[1, 1024\\]","errorType":"validation","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1180,"sourceCode":"                throw new MQClientException(\n                    \"pullThresholdSizeForTopic Out of range [1, 102400]\"\n                        + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                    null);\n            }\n        }\n\n        // pullInterval\n        if (this.defaultMQPushConsumer.getPullInterval() < 0 || this.defaultMQPushConsumer.getPullInterval() > 65535) {\n            throw new MQClientException(\n                \"pullInterval Out of range [0, 65535]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // consumeMessageBatchMaxSize\n        if (this.defaultMQPushConsumer.getConsumeMessageBatchMaxSize() < 1\n            || 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 + \"]\"","sourceCodeStart":1162,"sourceCodeEnd":1198,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1162-L1198","documentation":"Thrown during push-consumer startup when consumeMessageBatchMaxSize is outside [1, 1024]. This is the maximum number of messages passed to a single MessageListenerConcurrently.onMessage(List) invocation when the batch listener interface is used. The lower bound of 1 exists because at least one message per call is required, and the upper bound caps the batch to protect heap and acknowledgment granularity.","triggerScenarios":"Calling consumer.setConsumeMessageBatchMaxSize(n) with n < 1 or n > 1024 followed by consumer.start(). Only relevant when the consumer was created with a List-based (batch) message listener, but the validation runs for all push consumers.","commonSituations":"Setting 0 thinking it disables batching (it does not — it breaks the contract); raising the batch size far beyond pullBatchSize, which wastes the setting since a consume batch can never exceed what was pulled; copy-paste of pullBatchSize tuning into the consume field.","solutions":["Set consumeMessageBatchMaxSize to a value in [1, 1024] (default 1)","Keep consumeMessageBatchMaxSize <= pullBatchSize, otherwise pulls limit the effective consume batch anyway","For throughput tuning, raise both pullBatchSize and consumeMessageBatchMaxSize together in moderate steps"],"exampleFix":"// before\nconsumer.setConsumeMessageBatchMaxSize(0); // invalid: minimum is 1\n// after\nconsumer.setConsumeMessageBatchMaxSize(16); // batch of 16 per listener call\nconsumer.setPullBatchSize(32); // keep >= consume batch","handlingStrategy":"validation","validationCode":"int v = consumer.getConsumeMessageBatchMaxSize();\nif (v < 1 || v > 1024) throw new IllegalArgumentException(\"consumeMessageBatchMaxSize must be in [1,1024]: \" + v);\nif (v > consumer.getPullBatchSize()) log.warn(\"consume batch > pull batch; effective batch capped by pullBatchSize\");\nconsumer.start();","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getMessage().contains(\"consumeMessageBatchMaxSize\")) throw new ConfigException(e); throw e; }","preventionTips":["Keep consumeMessageBatchMaxSize <= pullBatchSize","0 is never valid; batching off == 1"],"tags":["rocketmq","consumer","configuration","batching","validation"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}