{"record":{"id":"af0430e79a4117db","repo":"apache/rocketmq","slug":"pullbatchsize-out-of-range-1-1024","errorCode":null,"errorMessage":"pullBatchSize Out of range [1, 1024]","messagePattern":"pullBatchSize 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":1188,"sourceCode":"        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 + \"]\"\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]\"","sourceCodeStart":1170,"sourceCodeEnd":1206,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1170-L1206","documentation":"Thrown during push-consumer startup when pullBatchSize is outside [1, 1024]. This is the maximum number of messages the client requests from the broker in a single pull call. Values below 1 cannot fetch anything and values above 1024 exceed the broker-side pull limit, so the client rejects them eagerly.","triggerScenarios":"Calling consumer.setPullBatchSize(n) with n < 1 or n > 1024, then consumer.start(). Independent of consumeMessageBatchMaxSize, but interacts with it.","commonSituations":"Setting 0 or a negative number by mistake in a property file; pushing the value above 1024 while tuning for very large messages — which anyway causes oversized requests that the broker would reject; forgetting that a big pullBatchSize with large messages can exceed consumer memory even when below 1024.","solutions":["Set pullBatchSize in [1, 1024] (default 32)","For large messages, lower pullBatchSize and consider pullThresholdSizeForQueue so size-based flow control kicks in before heap pressure","If more throughput is needed, scale with more queue/consumer instances instead of an oversized pull batch"],"exampleFix":"// before\nconsumer.setPullBatchSize(5000); // > 1024\n// after\nconsumer.setPullBatchSize(256); // in range; tune upward only with measured heap headroom","handlingStrategy":"validation","validationCode":"int v = consumer.getPullBatchSize();\nif (v < 1 || v > 1024) throw new IllegalArgumentException(\"pullBatchSize must be in [1,1024]: \" + v);\nconsumer.start();","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getMessage().contains(\"pullBatchSize\")) throw new ConfigException(e); throw e; }","preventionTips":["When messages are large, bound memory with pullThresholdSizeForQueue instead of raising pullBatchSize","Do not copy consumeMessageBatchMaxSize tuning into pullBatchSize blindly"],"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"}