apache/rocketmq · error · MQClientException

Unknown why, Can not find Message Queue for this topic, ${to

Error message

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

What it means

Fall-through case of fetchPublishMessageQueues: the name server returned a route without throwing, but it was null or produced a TopicPublishInfo that is not ok() (no writable queues for this client). Since no exception explains it, the client reports 'Unknown why'. In practice it means the route exists but contains no queues this producer can publish to (e.g. perm rejects write, or route lacks queue data).

Source

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

        } 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);
            if (topicRouteData != null) {
                Set<MessageQueue> mqList = MQClientInstance.topicRouteData2TopicSubscribeInfo(topic, topicRouteData);
                if (!mqList.isEmpty()) {

View on GitHub (pinned to 293f588571)

Solutions

1. Inspect the topic's route and perms: mqadmin topicRoute -t <topic> -n <namesrv> and update to perm 6 if read-only
2. Recreate/extend the topic with explicit queue nums on all target brokers
3. Verify you point at the correct cluster/name server for this topic

TopicRouteData route = /* raw route fetch */;
boolean writable = route != null && route.getQueueDatas().stream()
    .anyMatch(qd -> org.apache.rocketmq.common.protocol.body.PermName.isWriteable(qd.getPerm())
        && qd.getReadQueueNums() >= 0);
if (!writable) throw new IllegalStateException("no writable queues for " + topic);

try {
    producer.fetchPublishMessageQueues(topic);
} catch (MQClientException e) {
    if (e.getMessage().startsWith("Unknown why")) {
        // inspect mqadmin topicRoute; check perms and queue nums
    }
}

When it happens

Trigger: fetchPublishMessageQueues(topic) where the topic route has zero write queues or the topic exists only on brokers whose perm is read-only (perm=2/3).

Common situations: Topic created with read-only permission; partial route during broker registration; comparing envs where the topic exists in one cluster and not the other.

Related errors

• Not found broker, maybe key is wrong
• Can not find Message Queue for this topic, ${topic}
• 16
• create new topic failed
• Can not find Message Queue for this topic, ${topic} Namesrv

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