apache/rocketmq · error · MQClientException

Invoke Broker[${brokerAddr}] exception

Error message

Invoke Broker[${brokerAddr}] exception

What it means

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.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java:206

    public long searchOffset(MessageQueue mq, long timestamp) throws MQClientException {
        // default return lower boundary offset when there are more than one offsets.
        return searchOffset(mq, timestamp, BoundaryType.LOWER);
    }

    public long searchOffset(MessageQueue mq, long timestamp, BoundaryType boundaryType) throws MQClientException {
        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));
        if (null == brokerAddr) {
            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());
            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));
        }

        if (brokerAddr != null) {
            try {
                return this.mQClientFactory.getMQClientAPIImpl().searchOffset(brokerAddr, mq, timestamp,
                    boundaryType, timeoutMillis);
            } catch (Exception e) {
                throw new MQClientException("Invoke Broker[" + brokerAddr + "] exception", e);
            }
        }

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

    public long maxOffset(MessageQueue mq) throws MQClientException {
        String brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));
        if (null == brokerAddr) {
            this.mQClientFactory.updateTopicRouteInfoFromNameServer(mq.getTopic());
            brokerAddr = this.mQClientFactory.findBrokerAddressInPublish(this.mQClientFactory.getBrokerNameFromMessageQueue(mq));
        }

        if (brokerAddr != null) {
            try {
                return this.mQClientFactory.getMQClientAPIImpl().getMaxOffset(brokerAddr, mq, timeoutMillis);
            } catch (Exception e) {
                throw new MQClientException("Invoke Broker[" + brokerAddr + "] exception", e);

View on GitHub (pinned to 293f588571)

Solutions

1. Read e.getCause() to distinguish timeout vs broker-side rejection
2. Retry with a larger timeout (configure the admin's timeoutMillis) or after load subsides
3. Check broker health (logs, mqadmin brokerStatus) if failures persist

try {
    long off = mqAdmin.searchOffset(mq, timestamp);
} catch (MQClientException e) {
    Throwable c = e.getCause();
    if (c instanceof RemotingTimeoutException) {
        // retry with larger timeoutMillis
    }
}

When it happens

Trigger: 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.

Common situations: Calling searchOffset against a broker mid-GC/restart; large clock-skew timestamps triggering broker-side errors; heavy load pushing RPC latency past the timeout.

Related errors

• The broker[${brokerName}] not exist
• Failed to get max offset in queue
• Failed to get max offset in queue
• The broker[${brokerName}] not exist
• Not found broker, maybe key is wrong

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