apache/rocketmq · error · MQClientException

The topic[{topic}] not exist

Error message

The topic[{topic}] not exist

What it means

Thrown by fetchSubscribeMessageQueues when the client cannot obtain route (subscribe) information for the topic. The method first checks the local rebalanceImpl topic-subscribe table, then asks the name server to update the route; if both leave the entry null, no queue set exists for the topic and an MQClientException is thrown. This means the topic is unknown to the name server or the client could not pull its route.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java:206

    }

    public void createTopic(String key, String newTopic, int queueNum) throws MQClientException {
        createTopic(key, newTopic, queueNum, 0);
    }

    public void createTopic(String key, String newTopic, int queueNum, int topicSysFlag) throws MQClientException {
        this.mQClientFactory.getMQAdminImpl().createTopic(key, newTopic, queueNum, topicSysFlag, null);
    }

    public Set<MessageQueue> fetchSubscribeMessageQueues(String topic) throws MQClientException {
        Set<MessageQueue> result = this.rebalanceImpl.getTopicSubscribeInfoTable().get(topic);
        if (null == result) {
            this.mQClientFactory.updateTopicRouteInfoFromNameServer(topic);
            result = this.rebalanceImpl.getTopicSubscribeInfoTable().get(topic);
        }

        if (null == result) {
            throw new MQClientException("The topic[" + topic + "] not exist", null);
        }

        return parseSubscribeMessageQueues(result);
    }

    public Set<MessageQueue> parseSubscribeMessageQueues(Set<MessageQueue> messageQueueList) {
        Set<MessageQueue> resultQueues = new HashSet<>();
        for (MessageQueue queue : messageQueueList) {
            String userTopic = NamespaceUtil.withoutNamespace(queue.getTopic(), this.defaultMQPushConsumer.getNamespace());
            resultQueues.add(new MessageQueue(userTopic, queue.getBrokerName(), queue.getQueueId()));
        }

        return resultQueues;
    }

    public DefaultMQPushConsumer getDefaultMQPushConsumer() {
        return defaultMQPushConsumer;
    }

View on GitHub (pinned to 293f588571)

Solutions

1. Verify the topic exists: mqadmin topicList -n <namesrv> or DefaultMQAdminExt.topicList/examineTopicRouteInfo, and create it with mqadmin updateTopic if missing
2. Check namesrvAddr on the consumer matches the environment where the topic was created
3. If using a namespace, pass the namespace-qualified topic (or set the namespace on the consumer) so the route lookup matches
4. Ensure brokers have registered with the name server (broker restart or registration failure leaves topics unroutable)

Example fix

// before
consumer.subscribe("order-topic", "*"); // topic never created, name server has no route

// after
// create the topic first (broker with autoCreateTopicEnable=false)
DefaultMQAdminExt admin = new DefaultMQAdminExt();
admin.setNamesrvAddr(namesrvAddr);
admin.start();
admin.createTopic("broker-a", "order-topic", 8);
admin.shutdown();
consumer.subscribe("order-topic", "*");

// before subscribing/fetching, confirm the route exists
DefaultMQAdminExt admin = new DefaultMQAdminExt();
admin.setNamesrvAddr(namesrvAddr);
admin.start();
boolean exists = admin.examineTopicRouteInfo(topic) != null;
admin.shutdown();
if (!exists) throw new IllegalStateException("Topic missing on name server: " + topic);

try {
    Set<MessageQueue> qs = consumer.fetchSubscribeMessageQueues(topic);
} catch (MQClientException e) {
    if (e.getMessage().contains("not exist")) {
        // re-check route / create topic, then retry after backoff
    } else throw e;
}

When it happens

Trigger: Calling consumer.fetchSubscribeMessageQueues(topic) (or an API that delegates to it) for a topic that was never created, is spelled wrong, lives in a different namespace/environment, or when the name server is unreachable so updateTopicRouteInfoFromNameServer silently fails to populate the table.

Common situations: Topic created with autoCreateTopicEnable=false on the broker; consuming in a namespace-prefixed environment (e.g. namespace applied via instanceName/namespace config) so the full topic name differs; pointing the client at the wrong namesrvAddr; typos in the topic string.

Related errors

• 17
• topic list is empty.
• topic config is null.
• The specified topic is blank
• The specified topic is longer than topic max length %d.

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