{"record":{"id":"b22286ba3715ecea","repo":"apache/rocketmq","slug":"the-broker-desbrokername-not-exist","errorCode":null,"errorMessage":"The broker[{desBrokerName}] 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/consumer/DefaultMQPushConsumerImpl.java","lineNumber":887,"sourceCode":"            findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(desBrokerName, MixAll.MASTER_ID, true);\n        if (null == findBrokerResult) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(topic);\n            findBrokerResult = this.mQClientFactory.findBrokerAddressInSubscribe(desBrokerName, MixAll.MASTER_ID, true);\n        }\n        if (findBrokerResult != null) {\n            ChangeInvisibleTimeRequestHeader requestHeader = new ChangeInvisibleTimeRequestHeader();\n            requestHeader.setTopic(ExtraInfoUtil.getRealTopic(extraInfoStrs, topic, consumerGroup));\n            requestHeader.setQueueId(queueId);\n            requestHeader.setOffset(ExtraInfoUtil.getQueueOffset(extraInfoStrs));\n            requestHeader.setConsumerGroup(consumerGroup);\n            requestHeader.setExtraInfo(extraInfo);\n            requestHeader.setInvisibleTime(invisibleTime);\n            requestHeader.setBrokerName(brokerName);\n            //here the broker should be polished\n            this.mQClientFactory.getMQClientAPIImpl().changeInvisibleTimeAsync(brokerName, findBrokerResult.getBrokerAddr(), requestHeader, ASYNC_TIMEOUT, callback);\n            return;\n        }\n        throw new MQClientException(\"The broker[\" + desBrokerName + \"] not exist\", null);\n    }\n\n    public int getMaxReconsumeTimes() {\n        // default reconsume times: 16\n        if (this.defaultMQPushConsumer.getMaxReconsumeTimes() == -1) {\n            return 16;\n        } else {\n            return this.defaultMQPushConsumer.getMaxReconsumeTimes();\n        }\n    }\n\n    public void shutdown() {\n        shutdown(0);\n    }\n\n    public synchronized void shutdown(long awaitTerminateMillis) {\n        switch (this.serviceState) {\n            case CREATE_JUST:","sourceCodeStart":869,"sourceCodeEnd":905,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L869-L905","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the named broker is alive and registered: mqadmin brokerList / clusterList -n <namesrv>","Wait for the client's periodic route refresh (or restart the consumer) so the broker address table includes desBrokerName","If the broker was decommissioned, let the message retry on a healthy broker or drain/migrate its queues before removal","Retry the operation after the broker recovers — pop retries tolerate transient unavailability via reconsume"],"exampleFix":"// before\nconsumer.changeInvisibleTimeAsync(...); // desBroker 'broker-a' down / not in route table -> exception\n\n// after\n// guard: ensure broker reachable before retrying the invisible-time change\nif (consumer.getDefaultMQPushConsumerImpl() != null) {\n    // simplest robust pattern: rely on pop retry (ackTimeout/reconsume) instead of\n    // manual changeInvisibleTime against a possibly-dead broker:\n    message.setReconsumeTimes(message.getReconsumeTimes() + 1);\n    consumer.sendMessageBack(message); // routed via name server to a live broker\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    // pop retry / changeInvisibleTime path\n} catch (MQClientException e) {\n    if (e.getMessage().startsWith(\"The broker[\") && e.getMessage().endsWith(\"not exist\")) {\n        // schedule retry with backoff; route table will refresh from name server\n    } else throw e;\n}","preventionTips":["Prefer built-in pop retry (reconsume via sendMessageBack) over manual changeInvisibleTime against a specific broker","Monitor broker liveness (mqadmin brokerList) and drain queues before decommissioning a broker","Expect transient broker-unknown errors during broker restarts; make retry idempotent"],"tags":["rocketmq","pop-consumer","broker","routing"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}