apache/rocketmq · error · MQClientException

QUERY_NOT_FOUND

QUERY_NOT_FOUND

Error message

Failed to query consume offset from offset store

What it means

Thrown by RebalancePushImpl.computePullFromWhere when ConsumeFromWhere is CONSUME_FROM_LAST_OFFSET (the default) and the offset store returns neither a valid offset (>= 0) nor the -1 'no data' sentinel — i.e. readOffset returned -2 (READ_FROM_STORE failed, e.g. broker query error). With code QUERY_NOT_FOUND, it signals that the initial consume offset could not be determined for a queue at rebalance time.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/RebalancePushImpl.java:192

            case CONSUME_FROM_LAST_OFFSET: {
                long lastOffset = offsetStore.readOffset(mq, ReadOffsetType.READ_FROM_STORE);
                if (lastOffset >= 0) {
                    result = lastOffset;
                }
                // First start,no offset
                else if (-1 == lastOffset) {
                    if (mq.getTopic().startsWith(MixAll.RETRY_GROUP_TOPIC_PREFIX)) {
                        result = 0L;
                    } else {
                        try {
                            result = this.mQClientFactory.getMQAdminImpl().maxOffset(mq);
                        } catch (MQClientException e) {
                            log.warn("Compute consume offset from last offset exception, mq={}, exception={}", mq, e);
                            throw e;
                        }
                    }
                } else {
                    throw new MQClientException(ResponseCode.QUERY_NOT_FOUND, "Failed to query consume offset from " +
                            "offset store");
                }
                break;
            }
            case CONSUME_FROM_FIRST_OFFSET: {
                long lastOffset = offsetStore.readOffset(mq, ReadOffsetType.READ_FROM_STORE);
                if (lastOffset >= 0) {
                    result = lastOffset;
                } else if (-1 == lastOffset) {
                    //the offset will be fixed by the OFFSET_ILLEGAL process
                    result = 0L;
                } else {
                    throw new MQClientException(ResponseCode.QUERY_NOT_FOUND, "Failed to query offset from offset " +
                            "store");
                }
                break;
            }
            case CONSUME_FROM_TIMESTAMP: {

View on GitHub (pinned to 293f588571)

Solutions

1. Check broker connectivity and consumer permissions (consumerOffset query) — the underlying cause is logged just above by the offset store
2. If it is a brand-new consumer group, retry start/rebalance once the broker is reachable; first-run offset resolution then succeeds via maxOffset
3. Inspect the offset store: for local-file offsets check ~/.rocketmq_offsets corruption; for remote mode verify the broker holds the consumer group offsets
4. As a code-level guard, catch MQClientException with code QUERY_NOT_FOUND during start/rebalance and retry after a short delay

Example fix

// before
consumer.start(); // throws during first rebalance if broker offset query fails
// after
int attempts = 0;
while (true) {
    try { consumer.start(); break; }
    catch (MQClientException e) {
        if (++attempts > 3 || e.getResponseCode() != ResponseCode.QUERY_NOT_FOUND) throw e;
        Thread.sleep(3000); // broker may be briefly unreachable
    }
}

long probe = consumer.getDefaultMQPushConsumerImpl().getOffsetStore().readOffset(mq, ReadOffsetType.READ_FROM_STORE);
if (probe < -1) throw new IllegalStateException("offset store query failing (" + probe + "); check broker/ACL before start");

catch (MQClientException e) { if (e.getResponseCode() == ResponseCode.QUERY_NOT_FOUND) { scheduleRebalanceRetry(); } else throw e; }

When it happens

Trigger: Rebalance assigning a queue while offsetStore.readOffset(mq, READ_FROM_STORE) returns a negative value other than -1 — typically the remote offset query failed (broker unreachable, permission denied, or the consumer group offset genuinely absent combined with a query error) — and the topic is not a retry topic.

Common situations: First deployment of a consumer group where the offset query response is an error rather than 'not found'; broker briefly unavailable during rebalance; ACL/permission misconfiguration preventing consumerOffset queries; offset store corrupted locally (localFile mode) returning -2.

Related errors

• allocateMessageQueueStrategy is null
• The message queue is not in assigned list, may be rebalancin
• Seek offset illegal, seek offset =
• Fetch consume offset from broker exception
• offset < 0

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