{"record":{"id":"877a1d93373effc9","repo":"apache/rocketmq","slug":"the-broker-brokername-not-exist","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/consumer/store/RemoteBrokerOffsetStore.java","lineNumber":231,"sourceCode":"        }\n\n        if (findBrokerResult != null) {\n            UpdateConsumerOffsetRequestHeader requestHeader = new UpdateConsumerOffsetRequestHeader();\n            requestHeader.setTopic(mq.getTopic());\n            requestHeader.setConsumerGroup(this.groupName);\n            requestHeader.setQueueId(mq.getQueueId());\n            requestHeader.setCommitOffset(offset);\n            requestHeader.setBrokerName(mq.getBrokerName());\n\n            if (isOneway) {\n                this.mQClientFactory.getMQClientAPIImpl().updateConsumerOffsetOneway(\n                    findBrokerResult.getBrokerAddr(), requestHeader, 1000 * 5);\n            } else {\n                this.mQClientFactory.getMQClientAPIImpl().updateConsumerOffset(\n                    findBrokerResult.getBrokerAddr(), requestHeader, 1000 * 5);\n            }\n        } else {\n            throw new MQClientException(\"The broker[\" + mq.getBrokerName() + \"] not exist\", null);\n        }\n    }\n\n    private long fetchConsumeOffsetFromBroker(MessageQueue mq) throws RemotingException, MQBrokerException,\n        InterruptedException, MQClientException {\n        FindBrokerResult findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(this.mQClientFactory.getBrokerNameFromMessageQueue(mq), MixAll.MASTER_ID, true);\n        if (null == findBrokerResult) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());\n            findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(this.mQClientFactory.getBrokerNameFromMessageQueue(mq), MixAll.MASTER_ID, false);\n        }\n\n        if (findBrokerResult != null) {\n            QueryConsumerOffsetRequestHeader requestHeader = new QueryConsumerOffsetRequestHeader();\n            requestHeader.setTopic(mq.getTopic());\n            requestHeader.setConsumerGroup(this.groupName);\n            requestHeader.setQueueId(mq.getQueueId());\n            requestHeader.setBrokerName(mq.getBrokerName());\n","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/consumer/store/RemoteBrokerOffsetStore.java#L213-L249","documentation":"RemoteBrokerOffsetStore.updateConsumeOffsetToBroker resolves the broker master address via findBrokerAddressInSubscribe; after a route refresh it is still null, so persisting the offset is impossible and MQClientException('The broker[...] not exist') is thrown. It means the client's cached topic route no longer contains a reachable master for that broker name.","triggerScenarios":"A push/pull consumer in cluster mode persisting offsets while the broker master is down, decommissioned, or renamed (e.g. broker container restarted with a new name), or the name server route was updated and the old broker vanished.","commonSituations":"Broker failover where the slave is promoted but the client has not refreshed routes yet; typos in brokerName in ops tooling pointing at a broker that does not exist; k8s environments where broker pod names change.","solutions":["Verify the broker exists and its master is registered: sh mqadmin clusterList -n <namesrv>","If the broker name genuinely changed (recreate/restart with new identity), reset the consumer group's offsets for the old queues or wait for route refresh and let the client re-subscribe","Check name server connectivity — stale routes often come from the client being unable to pull updates","For persistent failures, use mqadmin consumerProgress to see the broker/group state"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    consumer.persistAll(mqs);\n} catch (MQClientException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"not exist\")) {\n        // route is stale: trigger updateTopicRouteInfoFromNameServer and retry once\n    }\n}","preventionTips":["Monitor broker liveness (mqadmin clusterList) in the same environment as consumers","Avoid renaming/recreating brokers with new identities while consumer groups hold offsets","Alert on repeated offset-persist failures instead of ignoring client logs"],"tags":["offsets","broker","routing","consumer","availability"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}