{"record":{"id":"eacdd12b11cf6fb2","repo":"apache/rocketmq","slug":"pullthresholdsizeforqueue-out-of-range-1-1024","errorCode":null,"errorMessage":"pullThresholdSizeForQueue Out of range [1, 1024]","messagePattern":"pullThresholdSizeForQueue 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":1153,"sourceCode":"            throw new MQClientException(\n                \"pullThresholdForQueue Out of range [1, 65535]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // pullThresholdForTopic\n        if (this.defaultMQPushConsumer.getPullThresholdForTopic() != -1) {\n            if (this.defaultMQPushConsumer.getPullThresholdForTopic() < 1 || this.defaultMQPushConsumer.getPullThresholdForTopic() > 6553500) {\n                throw new MQClientException(\n                    \"pullThresholdForTopic Out of range [1, 6553500]\"\n                        + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                    null);\n            }\n        }\n\n        // pullThresholdSizeForQueue\n        if (this.defaultMQPushConsumer.getPullThresholdSizeForQueue() < 1 || this.defaultMQPushConsumer.getPullThresholdSizeForQueue() > 1024) {\n            throw new MQClientException(\n                \"pullThresholdSizeForQueue Out of range [1, 1024]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        if (this.defaultMQPushConsumer.getPullThresholdSizeForTopic() != -1) {\n            // pullThresholdSizeForTopic\n            if (this.defaultMQPushConsumer.getPullThresholdSizeForTopic() < 1 || this.defaultMQPushConsumer.getPullThresholdSizeForTopic() > 102400) {\n                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(","sourceCodeStart":1135,"sourceCodeEnd":1171,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1135-L1171","documentation":"Thrown during DefaultMQPushConsumer startup (checkClientInBroker / checkConfig) when pullThresholdSizeForQueue is outside [1, 1024]. This is the per-queue flow-control threshold in MiB: when the estimated unread message size for a queue exceeds it, pulling is paused. The client validates configuration eagerly so an invalid flow-control value fails fast instead of causing unbounded memory growth.","triggerScenarios":"Calling consumer.start() (or producer/consumer factory start that runs checkConfig) with defaultMQPushConsumer.setPullThresholdSizeForQueue(n) where n < 1 or n > 1024. Note that, unlike pullThresholdSizeForTopic, this check is unconditional — there is no -1 sentinel to skip it.","commonSituations":"Copying a config template tuned for a very large heap and setting a value above 1024 MiB per queue; setting 0 or a negative number intending to 'disable' the limit (the API has no disable sentinel for this field); property-file typos that parse to 0.","solutions":["Set pullThresholdSizeForQueue to a value in [1, 1024] (default is 100 MiB), e.g. consumer.setPullThresholdSizeForQueue(100);","If you meant to disable per-queue limiting in favor of topic-level limiting, keep this field in range and instead set pullThresholdSizeForTopic (which accepts -1 to stay inactive)","If you truly need >1024 MiB per queue, raise pullThresholdSizeForTopic instead and split queues across more consumers"],"exampleFix":"// before\nconsumer.setPullThresholdSizeForQueue(2048); // MiB, > 1024\nconsumer.start();\n// after\nconsumer.setPullThresholdSizeForQueue(1024); // max allowed per queue\nconsumer.setPullThresholdSizeForTopic(10240); // tune at topic level if more headroom needed\nconsumer.start();","handlingStrategy":"validation","validationCode":"int v = consumer.getPullThresholdSizeForQueue();\nif (v < 1 || v > 1024) throw new IllegalArgumentException(\"pullThresholdSizeForQueue must be in [1,1024] MiB: \" + v);\nconsumer.start();","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getMessage().contains(\"pullThresholdSizeForQueue\")) throw new ConfigException(e); throw e; }","preventionTips":["Centralize consumer construction in one factory that clamps/validates all numeric ranges before start()","Document that this field is MiB and has no disable sentinel (unlike the -1 of the topic variant)","Add config-schema validation in your deploy pipeline for all RocketMQ tuning keys"],"tags":["rocketmq","consumer","configuration","flow-control","validation"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}