{"record":{"id":"d16a914cdfbe6ddd","repo":"apache/rocketmq","slug":"pullasync-unknown-exception","errorCode":null,"errorMessage":"pullAsync unknown exception","messagePattern":"pullAsync unknown exception","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java","lineNumber":562,"sourceCode":"                this.defaultMQPullConsumer.getBrokerSuspendMaxTimeMillis(),\n                timeoutMillis,\n                CommunicationMode.ASYNC,\n                new PullCallback() {\n\n                    @Override\n                    public void onSuccess(PullResult pullResult) {\n                        PullResult userPullResult = DefaultMQPullConsumerImpl.this.pullAPIWrapper.processPullResult(mq, pullResult, subscriptionData);\n                        resetTopic(userPullResult.getMsgFoundList());\n                        pullCallback.onSuccess(userPullResult);\n                    }\n\n                    @Override\n                    public void onException(Throwable e) {\n                        pullCallback.onException(e);\n                    }\n                });\n        } catch (MQBrokerException e) {\n            throw new MQClientException(\"pullAsync unknown exception\", e);\n        }\n    }\n\n    private void pullAsyncImpl(\n            final MessageQueue mq,\n            final SubscriptionData subscriptionData,\n            final long offset,\n            final int maxNums,\n            final PullCallback pullCallback,\n            final boolean block,\n            final long timeout) throws MQClientException, RemotingException, InterruptedException {\n        pullAsyncImpl(\n                mq,\n                subscriptionData,\n                offset,\n                maxNums,\n                Integer.MAX_VALUE,\n                pullCallback,","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java#L544-L580","documentation":"Thrown by pullAsyncImpl when the underlying pullKernelImpl call raises an MQBrokerException. Because the async protocol has no callback to deliver a broker-side failure, the exception is wrapped in an MQClientException with the generic label 'pullAsync unknown exception'; the original broker error (response code and remark) is preserved as the cause.","triggerScenarios":"Broker returns a non-zero ResponseCode during an async pull: OFFSET_ILLEGAL / OFFSET_OVERFLOW_BADLY when the offset is out of the queue's valid range, SUBSCRIPTION_GROUP_NOT_EXIST, FILTER_DATA_NOT_EXIST, or BROKER suspended; the wrapping happens in the catch (MQBrokerException e) around pullAPIWrapper.pullKernelImpl.","commonSituations":"Pulling with an offset beyond maxOffset (e.g. after messages expired and the queue was truncated); consumer group not created on the broker (autoCreateSubscriptionGroup disabled); SQL92 filter class data not registered on the broker; broker overloaded returning SYSTEM_BUSY.","solutions":["Inspect e.getCause() (MQBrokerException) and its responseCode to find the real broker error","For offset problems re-sync via fetchMessageQueuesWithQueueOffset or seek to minOffset","For SUBSCRIPTION_GROUP_NOT_EXIST create the group on the broker or enable autoCreateSubscriptionGroup in dev","For filter issues ensure the same selector was used previously so the broker compiled the filter, or retry to let it upload"],"exampleFix":"// before\ncatch (MQClientException e) {\n    log.error(\"pull failed\", e); // opaque generic message\n}\n\n// after\ncatch (MQClientException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof MQBrokerException) {\n        MQBrokerException be = (MQBrokerException) cause;\n        if (be.getResponseCode() == ResponseCode.OFFSET_ILLEGAL) {\n            long off = consumer.minOffset(mq);\n            consumer.getOffsetStore().updateOffset(mq, off, false);\n            return; // next pull uses corrected offset\n        }\n    }\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (MQClientException e) {\n    if (e.getCause() instanceof MQBrokerException) {\n        MQBrokerException be = (MQBrokerException) e.getCause();\n        switch (be.getResponseCode()) {\n            case ResponseCode.OFFSET_ILLEGAL: /* resync offset */ break;\n            case ResponseCode.SUBSCRIPTION_GROUP_NOT_EXIST: /* create group */ break;\n            default: throw e;\n        }\n    } else throw e;\n}","preventionTips":["Always inspect the MQBrokerException cause for the real response code","Validate offsets against min/maxOffset before pulling","Ensure consumer groups and filters exist on the broker before async pulls"],"tags":["rocketmq","pull-consumer","broker-error","async-pull","offset-illegal"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}