apache/rocketmq · error · MQClientException

The broker[{desBrokerName}] not exist

Error message

The broker[{desBrokerName}] not exist

What it means

Thrown in the pop-consumer path (changeInvisibleTime flow) when the client cannot find address information for the destination broker named in the pop message's extra info (desBrokerName). findBrokerResult is null, so the async changeInvisibleTime call cannot be issued and the method falls through to this MQClientException.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java:887

            findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(desBrokerName, MixAll.MASTER_ID, true);
        if (null == findBrokerResult) {
            this.mQClientFactory.updateTopicRouteInfoFromNameServer(topic);
            findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(desBrokerName, MixAll.MASTER_ID, true);
        }
        if (findBrokerResult != null) {
            ChangeInvisibleTimeRequestHeader requestHeader = new ChangeInvisibleTimeRequestHeader();
            requestHeader.setTopic(ExtraInfoUtil.getRealTopic(extraInfoStrs, topic, consumerGroup));
            requestHeader.setQueueId(queueId);
            requestHeader.setOffset(ExtraInfoUtil.getQueueOffset(extraInfoStrs));
            requestHeader.setConsumerGroup(consumerGroup);
            requestHeader.setExtraInfo(extraInfo);
            requestHeader.setInvisibleTime(invisibleTime);
            requestHeader.setBrokerName(brokerName);
            //here the broker should be polished
            this.mQClientFactory.getMQClientAPIImpl().changeInvisibleTimeAsync(brokerName, findBrokerResult.getBrokerAddr(), requestHeader, ASYNC_TIMEOUT, callback);
            return;
        }
        throw new MQClientException("The broker[" + desBrokerName + "] not exist", null);
    }

    public int getMaxReconsumeTimes() {
        // default reconsume times: 16
        if (this.defaultMQPushConsumer.getMaxReconsumeTimes() == -1) {
            return 16;
        } else {
            return this.defaultMQPushConsumer.getMaxReconsumeTimes();
        }
    }

    public void shutdown() {
        shutdown(0);
    }

    public synchronized void shutdown(long awaitTerminateMillis) {
        switch (this.serviceState) {
            case CREATE_JUST:

View on GitHub (pinned to 293f588571)

Solutions

1. Verify the named broker is alive and registered: mqadmin brokerList / clusterList -n <namesrv>
2. Wait for the client's periodic route refresh (or restart the consumer) so the broker address table includes desBrokerName
3. If the broker was decommissioned, let the message retry on a healthy broker or drain/migrate its queues before removal
4. Retry the operation after the broker recovers — pop retries tolerate transient unavailability via reconsume

Example fix

// before
consumer.changeInvisibleTimeAsync(...); // desBroker 'broker-a' down / not in route table -> exception

// after
// guard: ensure broker reachable before retrying the invisible-time change
if (consumer.getDefaultMQPushConsumerImpl() != null) {
    // simplest robust pattern: rely on pop retry (ackTimeout/reconsume) instead of
    // manual changeInvisibleTime against a possibly-dead broker:
    message.setReconsumeTimes(message.getReconsumeTimes() + 1);
    consumer.sendMessageBack(message); // routed via name server to a live broker
}

try {
    // pop retry / changeInvisibleTime path
} catch (MQClientException e) {
    if (e.getMessage().startsWith("The broker[") && e.getMessage().endsWith("not exist")) {
        // schedule retry with backoff; route table will refresh from name server
    } else throw e;
}

When it happens

Trigger: Calling the changeInvisibleTime-related API (retry/re-consume of a popped message) when the broker named by the message's extra info is no longer in the client's broker table — broker down, renamed, not yet registered with the name server, or route info not yet refreshed on this client.

Common situations: Broker outage or restart while pop messages are being re-consumed; broker removed from the cluster (scale-down) while its messages are still being retried; client's route cache is stale right after startup or after a name server blip.

Related errors

• Failed to get max offset
• Failed to get max offset in queue
• Failed to ack message
• Failed to get max consume offset
• Failed to get max offset in queue or iterate in queue

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