{"record":{"id":"ae10edcff7e75dac","repo":"apache/rocketmq","slug":"invoke-broker-brokeraddr-exception","errorCode":null,"errorMessage":"Invoke Broker[${brokerAddr}] exception","messagePattern":"Invoke Broker\\[(.+?)\\] exception","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java","lineNumber":206,"sourceCode":"\n    public long searchOffset(MessageQueue mq, long timestamp) throws MQClientException {\n        // default return lower boundary offset when there are more than one offsets.\n        return searchOffset(mq, timestamp, BoundaryType.LOWER);\n    }\n\n    public long searchOffset(MessageQueue mq, long timestamp, BoundaryType boundaryType) throws MQClientException {\n        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        if (null == brokerAddr) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());\n            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        }\n\n        if (brokerAddr != null) {\n            try {\n                return this.mQClientFactory.getMQClientAPIImpl().searchOffset(brokerAddr, mq, timestamp,\n                    boundaryType, timeoutMillis);\n            } catch (Exception e) {\n                throw new MQClientException(\"Invoke Broker[\" + brokerAddr + \"] exception\", e);\n            }\n        }\n\n        throw new MQClientException(\"The broker[\" + mq.getBrokerName() + \"] not exist\", null);\n    }\n\n    public long maxOffset(MessageQueue mq) throws MQClientException {\n        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        if (null == brokerAddr) {\n            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());\n            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));\n        }\n\n        if (brokerAddr != null) {\n            try {\n                return this.mQClientFactory.getMQClientAPIImpl().getMaxOffset(brokerAddr, mq, timeoutMillis);\n            } catch (Exception e) {\n                throw new MQClientException(\"Invoke Broker[\" + brokerAddr + \"] exception\", e);","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java#L188-L224","documentation":"In MQAdminImpl.searchOffset(mq, timestamp, boundaryType), the broker master address was resolved, but the searchOffset RPC (querying the queue offset at a timestamp) threw — remoting timeout, broker error, interrupted. The client wraps it as MQClientException('Invoke Broker[addr] exception') preserving the cause. The failure is in the broker round-trip, not in route lookup.","triggerScenarios":"mqAdmin.searchOffset(mq, timestamp) when the broker is overloaded, restarting, or the network to it is slow — the 3s default RPC times out or the connection breaks.","commonSituations":"Calling searchOffset against a broker mid-GC/restart; large clock-skew timestamps triggering broker-side errors; heavy load pushing RPC latency past the timeout.","solutions":["Read e.getCause() to distinguish timeout vs broker-side rejection","Retry with a larger timeout (configure the admin's timeoutMillis) or after load subsides","Check broker health (logs, mqadmin brokerStatus) if failures persist"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    long off = mqAdmin.searchOffset(mq, timestamp);\n} catch (MQClientException e) {\n    Throwable c = e.getCause();\n    if (c instanceof RemotingTimeoutException) {\n        // retry with larger timeoutMillis\n    }\n}","preventionTips":["Size timeoutMillis to observed broker latency","Avoid offset queries during planned broker restarts"],"tags":["offsets","broker","rpc","timeout","admin"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}