apache/rocketmq · error · MQClientException

The broker[${brokerName}] not exist

Error message

The broker[${brokerName}] not exist

What it means

Terminal branch of MQAdminImpl.searchOffset: after a route refresh, no publishable broker address exists for mq.getBrokerName(), so the offset-by-timestamp query cannot be sent at all. As with [148]/[149], it means the MessageQueue references a broker this client cannot currently resolve as master.

Source

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

    }

    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));
        }

        if (brokerAddr != null) {
            try {
                return this.mQClientFactory.getMQClientAPIImpl().searchOffset(brokerAddr, mq, timestamp,
                    boundaryType, timeoutMillis);
            } catch (Exception e) {
                throw new MQClientException("Invoke Broker[" + brokerAddr + "] exception", e);
            }
        }

        throw new MQClientException("The broker[" + mq.getBrokerName() + "] not exist", null);
    }

    public long maxOffset(MessageQueue mq) 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));
        }

        if (brokerAddr != null) {
            try {
                return this.mQClientFactory.getMQClientAPIImpl().getMaxOffset(brokerAddr, mq, timeoutMillis);
            } catch (Exception e) {
                throw new MQClientException("Invoke Broker[" + brokerAddr + "] exception", e);
            }
        }

        throw new MQClientException("The broker[" + mq.getBrokerName() + "] not exist", null);

View on GitHub (pinned to 293f588571)

Solutions

1. Verify the broker is up and registered (mqadmin clusterList)
2. Re-obtain the queue from a fresh route (fetchPublishMessageQueues) instead of stale objects
3. Retry after broker recovery; treat persistent failure as a wrong-cluster/broker-name problem

// Refuse to query stale queues: broker must exist in current route
TopicRouteData route = /* fresh route */;
Set<String> live = route.getBrokerDatas().stream()
    .map(BrokerData::getBrokerName).collect(Collectors.toSet());
if (!live.contains(mq.getBrokerName())) {
    throw new IllegalStateException("stale MessageQueue; refetch from route");
}

try {
    mqAdmin.searchOffset(mq, ts);
} catch (MQClientException e) {
    if (e.getMessage().contains("not exist")) { /* refetch queues, retry once */ }
}

When it happens

Trigger: searchOffset on a MessageQueue whose broker is down, decommissioned, or whose name no longer matches the cluster's registered brokers.

Common situations: Reusing MessageQueue objects captured before a broker migration/rename; broker temporarily offline during query; wrong cluster targeted.

Related errors

• The broker[${brokerName}] not exist
• Not found broker, maybe key is wrong
• Invoke Broker[${brokerAddr}] exception
• Failed to get max offset in queue
• Failed to get max offset in queue

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