apache/rocketmq · error · MQClientException

17

17

Error message

The topic[${topic}] not matched route info

What it means

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.

Source

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

                    }
                }

                //If namespace not null , reset Topic without namespace.
                if (null != this.mQClientFactory.getClientConfig().getNamespace()) {
                    for (MessageExt messageExt : messageList) {
                        messageExt.setTopic(NamespaceUtil.withoutNamespace(messageExt.getTopic(), this.mQClientFactory.getClientConfig().getNamespace()));
                    }
                }

                if (!messageList.isEmpty()) {
                    return new QueryResult(indexLastUpdateTimestamp, messageList);
                } else {
                    throw new MQClientException(ResponseCode.NO_MESSAGE, "query message by key finished, but no message.");
                }
            }
        }

        throw new MQClientException(ResponseCode.TOPIC_NOT_EXIST, "The topic[" + topic + "] not matched route info");
    }
}

View on GitHub (pinned to 293f588571)

Solutions

1. Create the topic: sh mqadmin updateTopic -t <topic> -n <namesrv> (or enable auto-creation in dev)
2. Verify route: sh mqadmin topicRoute -t <topic> -n <namesrv>
3. Check client namesrvAddr and namespace settings match the target cluster
4. Confirm name servers are reachable from the client host
5. Call fetchMessageQueues(topic) first as an explicit existence check with a clearer failure

Example fix

// before
QueryResult r = admin.queryMessage("Tx", "k", 10, begin, end); // no route

// after: fail fast with explicit check
if (admin.fetchMessageQueues("Tx").isEmpty()) {
    throw new IllegalStateException("Topic Tx has no queues on this cluster");
}
QueryResult r = admin.queryMessage("Tx", "k", 10, begin, end);

// fail fast if no route exists
try {
    Collection<MessageQueue> qs = adminExt.fetchMessageQueues(topic);
    if (qs == null || qs.isEmpty()) throw new IllegalStateException("No route for " + topic);
} catch (MQClientException e) {
    throw new IllegalStateException("Topic missing or namesrv unreachable: " + topic, e);
}

try {
    QueryResult r = admin.queryMessage(topic, key, max, begin, end);
} catch (MQClientException e) {
    if (e.getResponseCode() == ResponseCode.TOPIC_NOT_EXIST) {
        // create topic or fix namesrv/namespace, then retry
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The topic[{topic}] not exist
• topic list is empty.
• topic config is null.
• the specified group is blank
• the specified group[%s] is longer than group max length: %s.

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