{"record":{"id":"8f773a668785c560","repo":"apache/rocketmq","slug":"the-broker-brokername-not-exist-8f773a","errorCode":null,"errorMessage":"The broker[{brokerName}] not exist","messagePattern":"The broker\\[(.+?)\\] not exist","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/PullAPIWrapper.java","lineNumber":251,"sourceCode":"            requestHeader.setExpressionType(expressionType);\n            requestHeader.setBrokerName(mq.getBrokerName());\n\n            String brokerAddr = findBrokerResult.getBrokerAddr();\n            if (PullSysFlag.hasClassFilterFlag(sysFlagInner)) {\n                brokerAddr = computePullFromWhichFilterServer(mq.getTopic(), brokerAddr);\n            }\n\n            PullResult pullResult = this.mQClientFactory.getMQClientAPIImpl().pullMessage(\n                brokerAddr,\n                requestHeader,\n                timeoutMillis,\n                communicationMode,\n                pullCallback);\n\n            return pullResult;\n        }\n\n        throw new MQClientException(\"The broker[\" + mq.getBrokerName() + \"] not exist\", null);\n    }\n\n    public PullResult pullKernelImpl(\n        MessageQueue mq,\n        final String subExpression,\n        final String expressionType,\n        final long subVersion,\n        long offset,\n        final int maxNums,\n        final int sysFlag,\n        long commitOffset,\n        final long brokerSuspendMaxTimeMillis,\n        final long timeoutMillis,\n        final CommunicationMode communicationMode,\n        PullCallback pullCallback\n    ) throws MQClientException, RemotingException, MQBrokerException, InterruptedException {\n        return pullKernelImpl(\n                mq,","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/PullAPIWrapper.java#L233-L269","documentation":"Thrown at the end of PullAPIWrapper.pullKernelImpl when findBrokerAddressInSubscribe cannot resolve a broker address for the queue's brokerName — including after a forced topic-route refresh. The client maintains a local map of broker name -> address; if the queue references a broker absent from that map (deleted broker, stale MessageQueue object, or route info not yet propagated), the pull cannot proceed.","triggerScenarios":"A pull (or pullCallback path) on a MessageQueue whose getBrokerName() is not in the client's brokerAddrTable, both before and after updateTopicRouteInfoFromNameServer is re-run inside this method. Typical after rebalance hands out queues for a broker that was just shut down, or when using a stale MessageQueue captured before a topology change.","commonSituations":"Broker decommissioned or crashed while consumers still held its queues; NameServer route propagation lag right after broker registration; client clock/network issues delaying route refresh; hard-coded MessageQueue objects in opencalls (assign mode) that outlive the broker.","solutions":["Retry after refreshing route data: the error is usually transient — call defaultMQAdminExt/updateTopicRouteInfoFromNameServer or simply restart/rebalance; push consumers retry automatically","Verify the broker actually exists: check broker registration in the NameServer console (sh mqadmin clusterList) and broker logs for registration failures","If the broker was intentionally removed, restart consumers so rebalance drops its queues; do not cache MessageQueue objects across topology changes","For long-lived assign-mode consumers, periodically re-resolve queues from the NameServer instead of caching them forever"],"exampleFix":"// before (assign-style long-lived queue object)\nMessageQueue mq = queues.get(0); // captured days ago, broker since removed\nPullResult r = consumer.pull(mq, \"*\", offset, 32); // -> broker not exist\n// after\n// re-resolve route before pulling\nconsumer.getDefaultMQPushConsumerImpl().getmQClientFactory().updateTopicRouteInfoFromNameServer(topic);\nSet<MessageQueue> live = consumer.fetchMessageQueues(topic); // use fresh queues only","handlingStrategy":"retry","validationCode":"clientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());\nSet<MessageQueue> live = consumer.fetchMessageQueues(mq.getTopic());\nif (!live.contains(mq)) throw new IllegalStateException(\"queue no longer in route: \" + mq);","typeGuard":null,"tryCatchPattern":"try { return pull(mq, sub, off, n); } catch (MQClientException e) { if (e.getMessage().endsWith(\"not exist\")) { refreshRoute(); return retryOnce(mq, sub, off, n); } throw e; }","preventionTips":["Never cache MessageQueue objects across topology changes; re-resolve per cycle","Monitor broker registration in the NameServer during decommissions","Expect transient route lag after broker restarts; back off briefly and retry"],"tags":["rocketmq","consumer","pull","name-server","route-discovery"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}