apache/rocketmq · error · MQClientException

Not found broker, maybe key is wrong

Error message

Not found broker, maybe key is wrong

What it means

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).

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java:136

                                    exception = new MQClientException("create topic to broker exception", e);
                                }
                            }
                        }

                        if (createOK) {
                            orderTopicString.append(brokerData.getBrokerName());
                            orderTopicString.append(":");
                            orderTopicString.append(queueNum);
                            orderTopicString.append(";");
                        }
                    }
                }

                if (exception != null && !createOKAtLeastOnce) {
                    throw exception;
                }
            } else {
                throw new MQClientException("Not found broker, maybe key is wrong", null);
            }
        } catch (Exception e) {
            throw new MQClientException("create new topic failed", e);
        }
    }

    public List<MessageQueue> fetchPublishMessageQueues(String topic) throws MQClientException {
        try {
            TopicRouteData topicRouteData = this.mQClientFactory.getMQClientAPIImpl().getTopicRouteInfoFromNameServer(topic, timeoutMillis);
            if (topicRouteData != null) {
                TopicPublishInfo topicPublishInfo = MQClientInstance.topicRouteData2TopicPublishInfo(topic, topicRouteData);
                if (topicPublishInfo != null && topicPublishInfo.ok()) {
                    return parsePublishMessageQueues(topicPublishInfo.getMessageQueueList());
                }
            }
        } catch (Exception e) {
            throw new MQClientException("Can not find Message Queue for this topic, " + topic, e);
        }

View on GitHub (pinned to 293f588571)

Solutions

1. List actual broker names with mqadmin clusterList and use the exact registered brokerName as the key
2. Create the topic via mqadmin updateTopic (b <broker> -n <namesrv>) which validates broker existence server-side
3. Retry after verifying all brokers have registered with the name server

// Confirm the key matches a registered broker before creating
Set<String> brokers = mqAdmin.fetchBrokerNames? : /* use route */
TopicRouteData route = client.getTopicRouteInfoFromNameServer(orderTopicKey, 3000);
if (route == null || route.getBrokerDatas().isEmpty()) {
    throw new IllegalStateException("key '" + key + "' matches no broker; check mqadmin clusterList");
}

try {
    mqAdmin.createTopic(orderTopicKey, newTopic, queues);
} catch (MQClientException e) {
    Throwable c = e.getCause();
    if (c instanceof MQClientException && String.valueOf(c.getMessage()).contains("Not found broker")) {
        // key/brokerName mismatch: re-run with exact registered broker name
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• create new topic failed
• Can not find Message Queue for this topic, ${topic}
• Unknown why, Can not find Message Queue for this topic, ${to
• The broker[${brokerName}] not exist
• Failed to get max offset in queue

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/20470e7818ee7dc9. Report an issue: GitHub.