apache/rocketmq · error · MQClientException

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

Error message

Can not find Message Queue for this topic, ${topic}
See https://rocketmq.apache.org/docs/faq/ for further details.

What it means

The catch branch of fetchSubscribeMessageQueues: an exception during route fetch/conversion (name server timeout, remoting error, TOPIC_NOT_EXIST) is wrapped as MQClientException with a FAQ link (MQLIST_NOT_EXIST). The cause is attached. This is the subscribe-side twin of error [152].

Source

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

            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()) {
                    return mqList;
                } else {
                    throw new MQClientException("Can not find Message Queue for this topic, " + topic + " Namesrv return empty", null);
                }
            }
        } catch (Exception e) {
            throw new MQClientException(
                "Can not find Message Queue for this topic, " + topic + FAQUrl.suggestTodo(FAQUrl.MQLIST_NOT_EXIST),
                e);
        }

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

    public long searchOffset(MessageQueue mq, long timestamp) throws MQClientException {
        // default return lower boundary offset when there are more than one offsets.
        return searchOffset(mq, timestamp, BoundaryType.LOWER);
    }

    public long searchOffset(MessageQueue mq, long timestamp, BoundaryType boundaryType) throws MQClientException {
        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));
        if (null == brokerAddr) {
            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());
            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));
        }

View on GitHub (pinned to 293f588571)

Solutions

1. Create the topic or enable auto-creation, then restart/rebalance the consumer
2. Validate name server address and network reachability from the client
3. Follow the FAQ link in the message — it enumerates these exact causes

try {
    consumer.fetchSubscribeMessageQueues(topic);
} catch (MQClientException e) {
    // cause holds the remoting/topic-not-exist error; create topic or fix nameserver, then retry
}

When it happens

Trigger: Consumer start or fetchSubscribeMessageQueues(topic) while the name server is unreachable or responds that the topic does not exist.

Common situations: Starting a consumer before the topic is created; misconfigured NAMESRV_ADDR; environment where name server ports are blocked.

Related errors

• Can not find Message Queue for this topic, ${topic} Namesrv
• add subscription exception
• Can not find Message Queue for this topic, ${topic}
• Topic can not be null or empty.
• subscription exception

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