apache/rocketmq · error · MQClientException

The broker[{}] not exist

Error message

The broker[{}] not exist

What it means

MQClientException thrown at the end of sendKernelImpl's retry loop over message queues: for every queue selected, tryToFindTopicPublishInfo's broker-addr lookup (findBrokerAddrByTopicName / the addr-by-name map) returned null, so no send was ever attempted and the loop exits to this throw naming the last broker tried. It means the client's route snapshot is stale or inconsistent - the queue list references a broker whose address the client cannot currently resolve (not registered, just unregistered, or master/replica info flipped during an election).

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/producer/DefaultMQProducerImpl.java:1100

                if (this.hasSendMessageHook()) {
                    context.setSendResult(sendResult);
                    this.executeSendMessageHookAfter(context);
                }

                return sendResult;
            } catch (RemotingException | InterruptedException | MQBrokerException e) {
                if (this.hasSendMessageHook()) {
                    context.setException(e);
                    this.executeSendMessageHookAfter(context);
                }
                throw e;
            } finally {
                msg.setBody(prevBody);
                msg.setTopic(NamespaceUtil.withoutNamespace(msg.getTopic(), this.defaultMQProducer.getNamespace()));
            }
        }

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

    public MQClientInstance getMqClientFactory() {
        return mQClientFactory;
    }

    @Deprecated
    public MQClientInstance getmQClientFactory() {
        return mQClientFactory;
    }

    private boolean tryToCompressMessage(final Message msg) {
        if (msg instanceof MessageBatch) {
            //batch does not support compressing right now
            return false;
        }
        byte[] body = msg.getBody();
        if (body != null) {

View on GitHub (pinned to 293f588571)

Solutions

1. Retry the send after a short backoff (route cache refreshes every 30s by default; force with producer.getDefaultMQProducerImpl().getMqClientFactory().updateTopicRouteInfoFromNameServer(topic) or createTopic/fetchPublishMessageQueues)
2. During planned restarts, drain/stop producers before brokers or accept transient failures with retry at the call site (e.g. Spring Retry, 2-3 attempts with 1-5s backoff)
3. Verify broker registration: mqadmin brokerStatus/clusterList -n <namesrv>; a broker persistently absent indicates genuine registration failure (check broker config, nameserver connectivity)
4. Keep client version reasonably current - route-change handling around broker elections has improved across releases

Example fix

// before
producer.send(msg); // throws 'broker not exist' during restart window
// after
RetryTemplate.of(3, Duration.ofSeconds(2)).execute(ctx -> producer.send(msg));
// or: for (int i=0;i<3;i++){ try { return producer.send(msg);} catch (MQClientException e){ Thread.sleep(2000);} }

 // optional: force route refresh before critical sends during known broker churn
producer.getDefaultMQProducerImpl().getMqClientFactory()
    .updateTopicRouteInfoFromNameServer(topic);

for (int i = 0; i < 3; i++) {
    try { return producer.send(msg); }
    catch (MQClientException e) {
        if (e.getMessage() != null && e.getMessage().contains("not exist")) {
            Thread.sleep(2_000); // route cache refresh window
            continue;
        }
        throw e;
    }
}
throw new IllegalStateException("send failed: broker route unavailable");

When it happens

Trigger: triggerScenarios

Common situations: commonSituations

Related errors

• No route info for this topic, {}
• NOT_FOUND_TOPIC_EXCEPTION
• 13
• Sending message to topic[%s] is forbidden.
• 17

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