apache/rocketmq · error · MQClientException

The broker[{brokerName}] not exist

Error message

The broker[{brokerName}] not exist

What it means

Thrown at the end of PullAPIWrapper.pullKernelImpl when findBrokerAddressInSubscribe cannot resolve a broker address for the queue's brokerName — including after a forced topic-route refresh. The client maintains a local map of broker name -> address; if the queue references a broker absent from that map (deleted broker, stale MessageQueue object, or route info not yet propagated), the pull cannot proceed.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/PullAPIWrapper.java:251

            requestHeader.setExpressionType(expressionType);
            requestHeader.setBrokerName(mq.getBrokerName());

            String brokerAddr = findBrokerResult.getBrokerAddr();
            if (PullSysFlag.hasClassFilterFlag(sysFlagInner)) {
                brokerAddr = computePullFromWhichFilterServer(mq.getTopic(), brokerAddr);
            }

            PullResult pullResult = this.mQClientFactory.getMQClientAPIImpl().pullMessage(
                brokerAddr,
                requestHeader,
                timeoutMillis,
                communicationMode,
                pullCallback);

            return pullResult;
        }

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

    public PullResult pullKernelImpl(
        MessageQueue mq,
        final String subExpression,
        final String expressionType,
        final long subVersion,
        long offset,
        final int maxNums,
        final int sysFlag,
        long commitOffset,
        final long brokerSuspendMaxTimeMillis,
        final long timeoutMillis,
        final CommunicationMode communicationMode,
        PullCallback pullCallback
    ) throws MQClientException, RemotingException, MQBrokerException, InterruptedException {
        return pullKernelImpl(
                mq,

View on GitHub (pinned to 293f588571)

Solutions

1. Retry after refreshing route data: the error is usually transient — call defaultMQAdminExt/updateTopicRouteInfoFromNameServer or simply restart/rebalance; push consumers retry automatically
2. Verify the broker actually exists: check broker registration in the NameServer console (sh mqadmin clusterList) and broker logs for registration failures
3. If the broker was intentionally removed, restart consumers so rebalance drops its queues; do not cache MessageQueue objects across topology changes
4. For long-lived assign-mode consumers, periodically re-resolve queues from the NameServer instead of caching them forever

Example fix

// before (assign-style long-lived queue object)
MessageQueue mq = queues.get(0); // captured days ago, broker since removed
PullResult r = consumer.pull(mq, "*", offset, 32); // -> broker not exist
// after
// re-resolve route before pulling
consumer.getDefaultMQPushConsumerImpl().getmQClientFactory().updateTopicRouteInfoFromNameServer(topic);
Set<MessageQueue> live = consumer.fetchMessageQueues(topic); // use fresh queues only

clientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());
Set<MessageQueue> live = consumer.fetchMessageQueues(mq.getTopic());
if (!live.contains(mq)) throw new IllegalStateException("queue no longer in route: " + mq);

try { return pull(mq, sub, off, n); } catch (MQClientException e) { if (e.getMessage().endsWith("not exist")) { refreshRoute(); return retryOnce(mq, sub, off, n); } throw e; }

When it happens

Trigger: A pull (or pullCallback path) on a MessageQueue whose getBrokerName() is not in the client's brokerAddrTable, both before and after updateTopicRouteInfoFromNameServer is re-run inside this method. Typical after rebalance hands out queues for a broker that was just shut down, or when using a stale MessageQueue captured before a topology change.

Common situations: Broker decommissioned or crashed while consumers still held its queues; NameServer route propagation lag right after broker registration; client clock/network issues delaying route refresh; hard-coded MessageQueue objects in opencalls (assign mode) that outlive the broker.

Related errors

• mq is null
• offset < 0
• maxNums <= 0
• mq is null
• parse subscription error

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