{"record":{"id":"a7583e43d8bff128","repo":"apache/rocketmq","slug":"the-broker-brokername-not-exist-a7583e","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/MQAdminImpl.java","lineNumber":210,"sourceCode":"    }\n\n    public long searchOffset(MessageQueue mq, long timestamp, BoundaryType boundaryType) throws MQClientException {\n        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        if (null == brokerAddr) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());\n            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        }\n\n        if (brokerAddr != null) {\n            try {\n                return this.mQClientFactory.getMQClientAPIImpl().searchOffset(brokerAddr, mq, timestamp,\n                    boundaryType, timeoutMillis);\n            } catch (Exception e) {\n                throw new MQClientException(\"Invoke Broker[\" + brokerAddr + \"] exception\", e);\n            }\n        }\n\n        throw new MQClientException(\"The broker[\" + mq.getBrokerName() + \"] not exist\", null);\n    }\n\n    public long maxOffset(MessageQueue mq) throws MQClientException {\n        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        if (null == brokerAddr) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());\n            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        }\n\n        if (brokerAddr != null) {\n            try {\n                return this.mQClientFactory.getMQClientAPIImpl().getMaxOffset(brokerAddr, mq, timeoutMillis);\n            } catch (Exception e) {\n                throw new MQClientException(\"Invoke Broker[\" + brokerAddr + \"] exception\", e);\n            }\n        }\n\n        throw new MQClientException(\"The broker[\" + mq.getBrokerName() + \"] not exist\", null);","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java#L192-L228","documentation":"Terminal branch of MQAdminImpl.searchOffset: after a route refresh, no publishable broker address exists for mq.getBrokerName(), so the offset-by-timestamp query cannot be sent at all. As with [148]/[149], it means the MessageQueue references a broker this client cannot currently resolve as master.","triggerScenarios":"searchOffset on a MessageQueue whose broker is down, decommissioned, or whose name no longer matches the cluster's registered brokers.","commonSituations":"Reusing MessageQueue objects captured before a broker migration/rename; broker temporarily offline during query; wrong cluster targeted.","solutions":["Verify the broker is up and registered (mqadmin clusterList)","Re-obtain the queue from a fresh route (fetchPublishMessageQueues) instead of stale objects","Retry after broker recovery; treat persistent failure as a wrong-cluster/broker-name problem"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Refuse to query stale queues: broker must exist in current route\nTopicRouteData route = /* fresh route */;\nSet<String> live = route.getBrokerDatas().stream()\n    .map(BrokerData::getBrokerName).collect(Collectors.toSet());\nif (!live.contains(mq.getBrokerName())) {\n    throw new IllegalStateException(\"stale MessageQueue; refetch from route\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    mqAdmin.searchOffset(mq, ts);\n} catch (MQClientException e) {\n    if (e.getMessage().contains(\"not exist\")) { /* refetch queues, retry once */ }\n}","preventionTips":["Always derive MessageQueue from a fresh fetchPublishMessageQueues","Never persist brokerNames in app config/databases"],"tags":["offsets","broker","routing","admin"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}