{"record":{"id":"f8f8a2e1b12e6da7","repo":"apache/rocketmq","slug":"pullthresholdsizefortopic-out-of-range-1-102400","errorCode":null,"errorMessage":"pullThresholdSizeForTopic Out of range [1, 102400]","messagePattern":"pullThresholdSizeForTopic Out of range \\[1, 102400\\]","errorType":"validation","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":1162,"sourceCode":"                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(\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(","sourceCodeStart":1144,"sourceCodeEnd":1180,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L1144-L1180","documentation":"Thrown during push-consumer startup when pullThresholdSizeForTopic is set to a value outside [1, 102400] (MiB). This is the topic-level back-pressure limit on total estimated unread message size across all queues of a topic. It is only validated when the value differs from the -1 sentinel, i.e. once you opt in the value must be in range.","triggerScenarios":"Calling consumer.setPullThresholdSizeForTopic(n) with n < 1 or n > 102400 and then consumer.start(). Leaving it at the default -1 never triggers this error.","commonSituations":"Setting the topic threshold below the per-queue threshold causing inconsistent flow control; copying broker-side limits (e.g. 1024000) into the client property; unit-to-unit confusion — the value is MiB, not bytes or KiB.","solutions":["Set the value in [1, 102400] MiB, or leave it unset (-1) if you only want per-queue limiting","Ensure pullThresholdSizeForTopic >= pullThresholdSizeForQueue * (expected queue count) so topic-level throttling does not strangle per-queue flow","Double-check the unit: the setter takes MiB, so remove any bytes-to-MiB conversion mistakes"],"exampleFix":"// before\nconsumer.setPullThresholdSizeForTopic(500 * 1024 * 1024); // treated as MiB, out of range\n// after\nconsumer.setPullThresholdSizeForTopic(10 * 1024); // 10240 MiB at topic level\n// or simply omit the setter to keep the -1 default","handlingStrategy":"validation","validationCode":"int v = consumer.getPullThresholdSizeForTopic();\nif (v != -1 && (v < 1 || v > 102400)) throw new IllegalArgumentException(\"pullThresholdSizeForTopic must be -1 or in [1,102400] MiB: \" + v);\nconsumer.start();","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getMessage().contains(\"pullThresholdSizeForTopic\")) throw new ConfigException(e); throw e; }","preventionTips":["Remember -1 means 'not set' and skips the check","Keep topic threshold >= per-queue threshold times queue count","Validate units (MiB) wherever the value enters your configuration"],"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"}