apache/rocketmq · error · MQClientException
The broker[${brokerName}] not exist
Error message
The broker[${brokerName}] not exist What it means
RemoteBrokerOffsetStore.updateConsumeOffsetToBroker resolves the broker master address via findBrokerAddressInSubscribe; after a route refresh it is still null, so persisting the offset is impossible and MQClientException('The broker[...] not exist') is thrown. It means the client's cached topic route no longer contains a reachable master for that broker name.
Source
Thrown at client/src/main/java/org/apache/rocketmq/client/consumer/store/RemoteBrokerOffsetStore.java:231
}
if (findBrokerResult != null) {
UpdateConsumerOffsetRequestHeader requestHeader = new UpdateConsumerOffsetRequestHeader();
requestHeader.setTopic(mq.getTopic());
requestHeader.setConsumerGroup(this.groupName);
requestHeader.setQueueId(mq.getQueueId());
requestHeader.setCommitOffset(offset);
requestHeader.setBrokerName(mq.getBrokerName());
if (isOneway) {
this.mQClientFactory.getMQClientAPIImpl().updateConsumerOffsetOneway(
findBrokerResult.getBrokerAddr(), requestHeader, 1000 * 5);
} else {
this.mQClientFactory.getMQClientAPIImpl().updateConsumerOffset(
findBrokerResult.getBrokerAddr(), requestHeader, 1000 * 5);
}
} else {
throw new MQClientException("The broker[" + mq.getBrokerName() + "] not exist", null);
}
}
private long fetchConsumeOffsetFromBroker(MessageQueue mq) throws RemotingException, MQBrokerException,
InterruptedException, MQClientException {
FindBrokerResult findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(this.mQClientFactory.getBrokerNameFromMessageQueue(mq), MixAll.MASTER_ID, true);
if (null == findBrokerResult) {
this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());
findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(this.mQClientFactory.getBrokerNameFromMessageQueue(mq), MixAll.MASTER_ID, false);
}
if (findBrokerResult != null) {
QueryConsumerOffsetRequestHeader requestHeader = new QueryConsumerOffsetRequestHeader();
requestHeader.setTopic(mq.getTopic());
requestHeader.setConsumerGroup(this.groupName);
requestHeader.setQueueId(mq.getQueueId());
requestHeader.setBrokerName(mq.getBrokerName());
View on GitHub (pinned to 293f588571)
Solutions
- Verify the broker exists and its master is registered: sh mqadmin clusterList -n <namesrv>
- If the broker name genuinely changed (recreate/restart with new identity), reset the consumer group's offsets for the old queues or wait for route refresh and let the client re-subscribe
- Check name server connectivity — stale routes often come from the client being unable to pull updates
- For persistent failures, use mqadmin consumerProgress to see the broker/group state
Defensive patterns
Strategy: retry
Try / catch
try {
consumer.persistAll(mqs);
} catch (MQClientException e) {
if (e.getMessage() != null && e.getMessage().contains("not exist")) {
// route is stale: trigger updateTopicRouteInfoFromNameServer and retry once
}
} Prevention
- Monitor broker liveness (mqadmin clusterList) in the same environment as consumers
- Avoid renaming/recreating brokers with new identities while consumer groups hold offsets
- Alert on repeated offset-persist failures instead of ignoring client logs
When it happens
Trigger: A push/pull consumer in cluster mode persisting offsets while the broker master is down, decommissioned, or renamed (e.g. broker container restarted with a new name), or the name server route was updated and the old broker vanished.
Common situations: Broker failover where the slave is promoted but the client has not refreshed routes yet; typos in brokerName in ops tooling pointing at a broker that does not exist; k8s environments where broker pod names change.
Related errors
- The broker[${brokerName}] not exist
- readLocalOffset Exception, maybe fastjson version too low Se
- Not found broker, maybe key is wrong
- Can not find Message Queue for this topic, ${topic} Namesrv
- Invoke Broker[${brokerAddr}] exception
AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14).
Data as JSON: /api/errors/877a1d93373effc9.
Report an issue: GitHub.