apache/rocketmq · error · MQClientException

Can not find Message Queue for this topic, ${topic}

Error message

Can not find Message Queue for this topic, ${topic}

What it means

In MQAdminImpl.fetchPublishMessageQueues, any exception while fetching the topic route from the name server (timeout, remoting error, topic-not-found response) is rethrown as MQClientException('Can not find Message Queue for this topic, <topic>') with the original cause attached. It fires only when the route lookup itself throws — not when the route is merely empty.

Source

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

            } 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);
        }

        throw new MQClientException("Unknown why, Can not find Message Queue for this topic, " + topic, null);
    }

    public List<MessageQueue> parsePublishMessageQueues(List<MessageQueue> messageQueueList) {
        List<MessageQueue> resultQueues = new ArrayList<>();
        for (MessageQueue queue : messageQueueList) {
            String userTopic = NamespaceUtil.withoutNamespace(queue.getTopic(), this.mQClientFactory.getClientConfig().getNamespace());
            resultQueues.add(new MessageQueue(userTopic, queue.getBrokerName(), queue.getQueueId()));
        }

        return resultQueues;
    }

    public Set<MessageQueue> fetchSubscribeMessageQueues(String topic) throws MQClientException {
        try {
            TopicRouteData topicRouteData = this.mQClientFactory.getMQClientAPIImpl().getTopicRouteInfoFromNameServer(topic, timeoutMillis);

View on GitHub (pinned to 293f588571)

Solutions

  1. Verify the topic exists: mqadmin topicStatus -n <namesrv> -t <topic>, create it if missing
  2. Check name server address and connectivity from the client host
  3. Retry with backoff if the failure was a transient timeout
Defensive patterns

Strategy: try-catch

Try / catch

try {
    List<MessageQueue> q = producer.fetchPublishMessageQueues(topic);
} catch (MQClientException e) {
    // cause distinguishes TOPIC_NOT_EXIST vs timeout; create topic or retry
}

Prevention

When it happens

Trigger: Calling defaultMQProducer.fetchPublishMessageQueues(topic)/mqAdmin.fetchPublishMessageQueues(topic) when getTopicRouteInfoFromNameServer throws — e.g. TOPIC_NOT_EXIST response, name server unreachable, or timeout.

Common situations: Fetching queues before the topic exists; wrong name server address in client config; name server briefly down during deploy.

Related errors

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