{"record":{"id":"72df4db30eb7d0d8","repo":"apache/rocketmq","slug":"17","errorCode":"17","errorMessage":"The topic[${topic}] not matched route info","messagePattern":"The topic\\[(.+?)\\] not matched route info","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java","lineNumber":505,"sourceCode":"                    }\n                }\n\n                //If namespace not null , reset Topic without namespace.\n                if (null != this.mQClientFactory.getClientConfig().getNamespace()) {\n                    for (MessageExt messageExt : messageList) {\n                        messageExt.setTopic(NamespaceUtil.withoutNamespace(messageExt.getTopic(), this.mQClientFactory.getClientConfig().getNamespace()));\n                    }\n                }\n\n                if (!messageList.isEmpty()) {\n                    return new QueryResult(indexLastUpdateTimestamp, messageList);\n                } else {\n                    throw new MQClientException(ResponseCode.NO_MESSAGE, \"query message by key finished, but no message.\");\n                }\n            }\n        }\n\n        throw new MQClientException(ResponseCode.TOPIC_NOT_EXIST, \"The topic[\" + topic + \"] not matched route info\");\n    }\n}\n","sourceCodeStart":487,"sourceCodeEnd":508,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java#L487-L508","documentation":"Thrown by MQAdminImpl.queryMessage with response code TOPIC_NOT_EXIST (17) when the client has no route information for the topic after attempting to fetch/update it from the name server. Without route data, the query cannot select a broker, so it aborts before contacting any server.","triggerScenarios":"Calling queryMessage with a topic that does not exist on the configured name servers, or exists only on another cluster. Also occurs when all name servers are unreachable so updateTopicRouteInfoFromNameServer fails silently, leaving the route table empty.","commonSituations":"Typo'd topic name; topic auto-creation disabled (autoCreateTopicEnable=false) and never manually created; NAMESRV_ADDR pointing to the wrong environment; name server outage; namespace prefix required by the client config but missing from the topic string.","solutions":["Create the topic: sh mqadmin updateTopic -t <topic> -n <namesrv> (or enable auto-creation in dev)","Verify route: sh mqadmin topicRoute -t <topic> -n <namesrv>","Check client namesrvAddr and namespace settings match the target cluster","Confirm name servers are reachable from the client host","Call fetchMessageQueues(topic) first as an explicit existence check with a clearer failure"],"exampleFix":"// before\nQueryResult r = admin.queryMessage(\"Tx\", \"k\", 10, begin, end); // no route\n\n// after: fail fast with explicit check\nif (admin.fetchMessageQueues(\"Tx\").isEmpty()) {\n    throw new IllegalStateException(\"Topic Tx has no queues on this cluster\");\n}\nQueryResult r = admin.queryMessage(\"Tx\", \"k\", 10, begin, end);","handlingStrategy":"validation","validationCode":"// fail fast if no route exists\ntry {\n    Collection<MessageQueue> qs = adminExt.fetchMessageQueues(topic);\n    if (qs == null || qs.isEmpty()) throw new IllegalStateException(\"No route for \" + topic);\n} catch (MQClientException e) {\n    throw new IllegalStateException(\"Topic missing or namesrv unreachable: \" + topic, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    QueryResult r = admin.queryMessage(topic, key, max, begin, end);\n} catch (MQClientException e) {\n    if (e.getResponseCode() == ResponseCode.TOPIC_NOT_EXIST) {\n        // create topic or fix namesrv/namespace, then retry\n    } else throw e;\n}","preventionTips":["Pre-create topics explicitly instead of relying on auto-creation","Include namespace prefix when the client config defines one","Health-check name server connectivity before running queries"],"tags":["rocketmq","topic","routing","name-server","client"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}