{"record":{"id":"067ea2f4d5df5ef8","repo":"apache/rocketmq","slug":"the-broker-not-exist","errorCode":null,"errorMessage":"The broker[{}] not exist","messagePattern":"The broker\\[(.+?)\\] not exist","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/producer/DefaultMQProducerImpl.java","lineNumber":1100,"sourceCode":"                if (this.hasSendMessageHook()) {\n                    context.setSendResult(sendResult);\n                    this.executeSendMessageHookAfter(context);\n                }\n\n                return sendResult;\n            } catch (RemotingException | InterruptedException | MQBrokerException e) {\n                if (this.hasSendMessageHook()) {\n                    context.setException(e);\n                    this.executeSendMessageHookAfter(context);\n                }\n                throw e;\n            } finally {\n                msg.setBody(prevBody);\n                msg.setTopic(NamespaceUtil.withoutNamespace(msg.getTopic(), this.defaultMQProducer.getNamespace()));\n            }\n        }\n\n        throw new MQClientException(\"The broker[\" + brokerName + \"] not exist\", null);\n    }\n\n    public MQClientInstance getMqClientFactory() {\n        return mQClientFactory;\n    }\n\n    @Deprecated\n    public MQClientInstance getmQClientFactory() {\n        return mQClientFactory;\n    }\n\n    private boolean tryToCompressMessage(final Message msg) {\n        if (msg instanceof MessageBatch) {\n            //batch does not support compressing right now\n            return false;\n        }\n        byte[] body = msg.getBody();\n        if (body != null) {","sourceCodeStart":1082,"sourceCodeEnd":1118,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/producer/DefaultMQProducerImpl.java#L1082-L1118","documentation":"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).","triggerScenarios":"triggerScenarios","commonSituations":"commonSituations","solutions":["Retry the send after a short backoff (route cache refreshes every 30s by default; force with producer.getDefaultMQProducerImpl().getMqClientFactory().updateTopicRouteInfoFromNameServer(topic) or createTopic/fetchPublishMessageQueues)","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)","Verify broker registration: mqadmin brokerStatus/clusterList -n <namesrv>; a broker persistently absent indicates genuine registration failure (check broker config, nameserver connectivity)","Keep client version reasonably current - route-change handling around broker elections has improved across releases"],"exampleFix":"// before\nproducer.send(msg); // throws 'broker not exist' during restart window\n// after\nRetryTemplate.of(3, Duration.ofSeconds(2)).execute(ctx -> producer.send(msg));\n// or: for (int i=0;i<3;i++){ try { return producer.send(msg);} catch (MQClientException e){ Thread.sleep(2000);} }","handlingStrategy":"retry","validationCode":" // optional: force route refresh before critical sends during known broker churn\nproducer.getDefaultMQProducerImpl().getMqClientFactory()\n    .updateTopicRouteInfoFromNameServer(topic);","typeGuard":null,"tryCatchPattern":"for (int i = 0; i < 3; i++) {\n    try { return producer.send(msg); }\n    catch (MQClientException e) {\n        if (e.getMessage() != null && e.getMessage().contains(\"not exist\")) {\n            Thread.sleep(2_000); // route cache refresh window\n            continue;\n        }\n        throw e;\n    }\n}\nthrow new IllegalStateException(\"send failed: broker route unavailable\");","preventionTips":["Wrap sends in bounded retry (2-3 attempts, seconds of backoff) to ride out broker restarts","Sequence deployments: drain producers before restarting brokers when possible","Monitor broker registration in the name server during rolling upgrades","Treat 'broker not exist' as transient (route churn) but alert if it persists past minutes"],"tags":["rocketmq","producer","routing","broker-failover","transient"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}