{"record":{"id":"b69d1dbf9a2ac0f1","repo":"apache/rocketmq","slug":"pullthresholdfortopic-out-of-range-1-6553500","errorCode":null,"errorMessage":"pullThresholdForTopic Out of range [1, 6553500]","messagePattern":"pullThresholdForTopic Out of range \\[1, 6553500\\]","errorType":"validation","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1144,"sourceCode":"            || this.defaultMQPushConsumer.getConsumeConcurrentlyMaxSpan() > 65535) {\n            throw new MQClientException(\n                \"consumeConcurrentlyMaxSpan Out of range [1, 65535]\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),\n                null);\n        }\n\n        // pullThresholdForQueue\n        if (this.defaultMQPushConsumer.getPullThresholdForQueue() < 1 || this.defaultMQPushConsumer.getPullThresholdForQueue() > 65535) {\n            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(","sourceCodeStart":1126,"sourceCodeEnd":1162,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1126-L1162","documentation":"checkConfig() validates pullThresholdForTopic — the topic-level total cap on cached messages across all queues that triggers flow control. The sentinel -1 means 'disabled/not set'; any other value must lie in [1, 6553500]. The error fires when a non-sentinel value falls outside that band.","triggerScenarios":"setPullThresholdForTopic(0) intending to disable (0 is invalid; only -1 disables); values above 6,553,500; inheriting 0 from a config default where the key was meant to stay unset.","commonSituations":"Config templates that default every numeric field to 0; migrating from per-queue to per-topic thresholds and using 0 as 'off'.","solutions":["Use -1 to disable the topic-level threshold, or set a value in [1,6553500]","Rule of thumb: set it to roughly (number of queues) * pullThresholdForQueue","Validate at config load that the field is -1 or within range so misconfigurations surface before start()"],"exampleFix":"// before\nconsumer.setPullThresholdForTopic(0); // invalid; 0 is not the disable sentinel\n\n// after\nconsumer.setPullThresholdForTopic(-1); // disabled, or e.g. 100000 within range","handlingStrategy":"validation","validationCode":"int t = config.getPullThresholdForTopic();\nif (t != -1 && (t < 1 || t > 6553500))\n    throw new IllegalArgumentException(\"pullThresholdForTopic must be -1 or in [1,6553500]: \" + t);\nconsumer.setPullThresholdForTopic(t);","typeGuard":"boolean validTopicThreshold(int v) { return v == -1 || (v >= 1 && v <= 6553500); }","tryCatchPattern":null,"preventionTips":["Use -1 (never 0) to disable the topic-level pull threshold","Size pullThresholdForTopic as queues * pullThresholdForQueue","Reject config templates that default numeric flow-control fields to 0"],"tags":["rocketmq","config","flow-control","validation"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}