{"record":{"id":"d1506f2dce8b1c0e","repo":"apache/rocketmq","slug":"the-topic-topic-not-exist","errorCode":null,"errorMessage":"The topic[{topic}] not exist","messagePattern":"The topic\\[(.+?)\\] not exist","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":206,"sourceCode":"    }\n\n    public void createTopic(String key, String newTopic, int queueNum) throws MQClientException {\n        createTopic(key, newTopic, queueNum, 0);\n    }\n\n    public void createTopic(String key, String newTopic, int queueNum, int topicSysFlag) throws MQClientException {\n        this.mQClientFactory.getMQAdminImpl().createTopic(key, newTopic, queueNum, topicSysFlag, null);\n    }\n\n    public Set<MessageQueue> fetchSubscribeMessageQueues(String topic) throws MQClientException {\n        Set<MessageQueue> result = this.rebalanceImpl.getTopicSubscribeInfoTable().get(topic);\n        if (null == result) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(topic);\n            result = this.rebalanceImpl.getTopicSubscribeInfoTable().get(topic);\n        }\n\n        if (null == result) {\n            throw new MQClientException(\"The topic[\" + topic + \"] not exist\", null);\n        }\n\n        return parseSubscribeMessageQueues(result);\n    }\n\n    public Set<MessageQueue> parseSubscribeMessageQueues(Set<MessageQueue> messageQueueList) {\n        Set<MessageQueue> resultQueues = new HashSet<>();\n        for (MessageQueue queue : messageQueueList) {\n            String userTopic = NamespaceUtil.withoutNamespace(queue.getTopic(), this.defaultMQPushConsumer.getNamespace());\n            resultQueues.add(new MessageQueue(userTopic, queue.getBrokerName(), queue.getQueueId()));\n        }\n\n        return resultQueues;\n    }\n\n    public DefaultMQPushConsumer getDefaultMQPushConsumer() {\n        return defaultMQPushConsumer;\n    }","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L188-L224","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the topic exists: mqadmin topicList -n <namesrv> or DefaultMQAdminExt.topicList/examineTopicRouteInfo, and create it with mqadmin updateTopic if missing","Check namesrvAddr on the consumer matches the environment where the topic was created","If using a namespace, pass the namespace-qualified topic (or set the namespace on the consumer) so the route lookup matches","Ensure brokers have registered with the name server (broker restart or registration failure leaves topics unroutable)"],"exampleFix":"// before\nconsumer.subscribe(\"order-topic\", \"*\"); // topic never created, name server has no route\n\n// after\n// create the topic first (broker with autoCreateTopicEnable=false)\nDefaultMQAdminExt admin = new DefaultMQAdminExt();\nadmin.setNamesrvAddr(namesrvAddr);\nadmin.start();\nadmin.createTopic(\"broker-a\", \"order-topic\", 8);\nadmin.shutdown();\nconsumer.subscribe(\"order-topic\", \"*\");","handlingStrategy":"retry","validationCode":"// before subscribing/fetching, confirm the route exists\nDefaultMQAdminExt admin = new DefaultMQAdminExt();\nadmin.setNamesrvAddr(namesrvAddr);\nadmin.start();\nboolean exists = admin.examineTopicRouteInfo(topic) != null;\nadmin.shutdown();\nif (!exists) throw new IllegalStateException(\"Topic missing on name server: \" + topic);","typeGuard":null,"tryCatchPattern":"try {\n    Set<MessageQueue> qs = consumer.fetchSubscribeMessageQueues(topic);\n} catch (MQClientException e) {\n    if (e.getMessage().contains(\"not exist\")) {\n        // re-check route / create topic, then retry after backoff\n    } else throw e;\n}","preventionTips":["Pre-create topics via mqadmin or infrastructure-as-code instead of relying on auto-creation","Validate topic existence in a startup health check before subscribing","Pin namesrvAddr per environment and verify connectivity (mqadmin clusterList) on deploy"],"tags":["rocketmq","topic","name-server","routing"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}