{"record":{"id":"20470e7818ee7dc9","repo":"apache/rocketmq","slug":"not-found-broker-maybe-key-is-wrong","errorCode":null,"errorMessage":"Not found broker, maybe key is wrong","messagePattern":"Not found broker, maybe key is wrong","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java","lineNumber":136,"sourceCode":"                                    exception = new MQClientException(\"create topic to broker exception\", e);\n                                }\n                            }\n                        }\n\n                        if (createOK) {\n                            orderTopicString.append(brokerData.getBrokerName());\n                            orderTopicString.append(\":\");\n                            orderTopicString.append(queueNum);\n                            orderTopicString.append(\";\");\n                        }\n                    }\n                }\n\n                if (exception != null && !createOKAtLeastOnce) {\n                    throw exception;\n                }\n            } else {\n                throw new MQClientException(\"Not found broker, maybe key is wrong\", null);\n            }\n        } catch (Exception e) {\n            throw new MQClientException(\"create new topic failed\", e);\n        }\n    }\n\n    public List<MessageQueue> fetchPublishMessageQueues(String topic) throws MQClientException {\n        try {\n            TopicRouteData topicRouteData = this.mQClientFactory.getMQClientAPIImpl().getTopicRouteInfoFromNameServer(topic, timeoutMillis);\n            if (topicRouteData != null) {\n                TopicPublishInfo topicPublishInfo = MQClientInstance.topicRouteData2TopicPublishInfo(topic, topicRouteData);\n                if (topicPublishInfo != null && topicPublishInfo.ok()) {\n                    return parsePublishMessageQueues(topicPublishInfo.getMessageQueueList());\n                }\n            }\n        } catch (Exception e) {\n            throw new MQClientException(\"Can not find Message Queue for this topic, \" + topic, e);\n        }","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java#L118-L154","documentation":"In MQAdminImpl's order-topic creation path, the client looks up route data for the order-topic key and finds nothing to iterate over — meaning no broker matched the key. The message ('Not found broker, maybe key is wrong') says the name server returned a route in which no broker matched the expected key (typically the broker name or order-topic key used to seed creation).","triggerScenarios":"Calling createTopic for an ordered topic where the map of broker->queue counts comes back empty because the key used to look up brokers does not match any registered broker name.","commonSituations":"BrokerName mismatch between ops script and cluster (case sensitivity, 'broker-a' vs 'broker-a-master'); creating the topic right after cluster re-registration where routes are inconsistent.","solutions":["List actual broker names with mqadmin clusterList and use the exact registered brokerName as the key","Create the topic via mqadmin updateTopic (b <broker> -n <namesrv>) which validates broker existence server-side","Retry after verifying all brokers have registered with the name server"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Confirm the key matches a registered broker before creating\nSet<String> brokers = mqAdmin.fetchBrokerNames? : /* use route */\nTopicRouteData route = client.getTopicRouteInfoFromNameServer(orderTopicKey, 3000);\nif (route == null || route.getBrokerDatas().isEmpty()) {\n    throw new IllegalStateException(\"key '\" + key + \"' matches no broker; check mqadmin clusterList\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    mqAdmin.createTopic(orderTopicKey, newTopic, queues);\n} catch (MQClientException e) {\n    Throwable c = e.getCause();\n    if (c instanceof MQClientException && String.valueOf(c.getMessage()).contains(\"Not found broker\")) {\n        // key/brokerName mismatch: re-run with exact registered broker name\n    }\n}","preventionTips":["Fetch broker names from the live cluster and use them verbatim","Prefer mqadmin updateTopic for one-off creation"],"tags":["topic","admin","routing","broker"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}