{"record":{"id":"8cff58e2498e4c3d","repo":"apache/rocketmq","slug":"query-not-found","errorCode":"QUERY_NOT_FOUND","errorMessage":"Failed to query consume offset from offset store","messagePattern":"Failed to query consume offset from offset store","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/RebalancePushImpl.java","lineNumber":192,"sourceCode":"            case CONSUME_FROM_LAST_OFFSET: {\n                long lastOffset = offsetStore.readOffset(mq, ReadOffsetType.READ_FROM_STORE);\n                if (lastOffset >= 0) {\n                    result = lastOffset;\n                }\n                // First start,no offset\n                else if (-1 == lastOffset) {\n                    if (mq.getTopic().startsWith(MixAll.RETRY_GROUP_TOPIC_PREFIX)) {\n                        result = 0L;\n                    } else {\n                        try {\n                            result = this.mQClientFactory.getMQAdminImpl().maxOffset(mq);\n                        } catch (MQClientException e) {\n                            log.warn(\"Compute consume offset from last offset exception, mq={}, exception={}\", mq, e);\n                            throw e;\n                        }\n                    }\n                } else {\n                    throw new MQClientException(ResponseCode.QUERY_NOT_FOUND, \"Failed to query consume offset from \" +\n                            \"offset store\");\n                }\n                break;\n            }\n            case CONSUME_FROM_FIRST_OFFSET: {\n                long lastOffset = offsetStore.readOffset(mq, ReadOffsetType.READ_FROM_STORE);\n                if (lastOffset >= 0) {\n                    result = lastOffset;\n                } else if (-1 == lastOffset) {\n                    //the offset will be fixed by the OFFSET_ILLEGAL process\n                    result = 0L;\n                } else {\n                    throw new MQClientException(ResponseCode.QUERY_NOT_FOUND, \"Failed to query offset from offset \" +\n                            \"store\");\n                }\n                break;\n            }\n            case CONSUME_FROM_TIMESTAMP: {","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/RebalancePushImpl.java#L174-L210","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check broker connectivity and consumer permissions (consumerOffset query) — the underlying cause is logged just above by the offset store","If it is a brand-new consumer group, retry start/rebalance once the broker is reachable; first-run offset resolution then succeeds via maxOffset","Inspect the offset store: for local-file offsets check ~/.rocketmq_offsets corruption; for remote mode verify the broker holds the consumer group offsets","As a code-level guard, catch MQClientException with code QUERY_NOT_FOUND during start/rebalance and retry after a short delay"],"exampleFix":"// before\nconsumer.start(); // throws during first rebalance if broker offset query fails\n// after\nint attempts = 0;\nwhile (true) {\n    try { consumer.start(); break; }\n    catch (MQClientException e) {\n        if (++attempts > 3 || e.getResponseCode() != ResponseCode.QUERY_NOT_FOUND) throw e;\n        Thread.sleep(3000); // broker may be briefly unreachable\n    }\n}","handlingStrategy":"retry","validationCode":"long probe = consumer.getDefaultMQPushConsumerImpl().getOffsetStore().readOffset(mq, ReadOffsetType.READ_FROM_STORE);\nif (probe < -1) throw new IllegalStateException(\"offset store query failing (\" + probe + \"); check broker/ACL before start\");","typeGuard":null,"tryCatchPattern":"catch (MQClientException e) { if (e.getResponseCode() == ResponseCode.QUERY_NOT_FOUND) { scheduleRebalanceRetry(); } else throw e; }","preventionTips":["Verify broker reachability and consumer-group ACL before first start of a new group","Retry consumer start with backoff when a broker is mid-restart","Keep local offset store files out of reach of disk-full/corruption conditions"],"tags":["rocketmq","consumer","offset","rebalance","startup"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}