{"record":{"id":"ae35537e260bc274","repo":"apache/rocketmq","slug":"the-consumer-service-state-not-ok-servicestate","errorCode":null,"errorMessage":"The consumer service state not OK, {serviceState}","messagePattern":"The consumer service state not OK, (.+?)","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java","lineNumber":678,"sourceCode":"            }\n\n            if (msgFoundList.size() != msgListFilterAgain.size()) {\n                for (MessageExt msg : msgFoundList) {\n                    if (!msgListFilterAgain.contains(msg)) {\n                        ackAsync(msg, this.groupName());\n                    }\n                }\n            }\n\n            popResult.setMsgFoundList(msgListFilterAgain);\n        }\n\n        return popResult;\n    }\n\n    private void makeSureStateOK() throws MQClientException {\n        if (this.serviceState != ServiceState.RUNNING) {\n            throw new MQClientException(\"The consumer service state not OK, \"\n                + this.serviceState\n                + FAQUrl.suggestTodo(FAQUrl.CLIENT_SERVICE_NOT_OK),\n                null);\n        }\n    }\n\n    void executePullRequestLater(final PullRequest pullRequest, final long timeDelay) {\n        this.mQClientFactory.getPullMessageService().executePullRequestLater(pullRequest, timeDelay);\n    }\n\n    public boolean isPause() {\n        return pause;\n    }\n\n    public void setPause(boolean pause) {\n        this.pause = pause;\n    }\n","sourceCodeStart":660,"sourceCodeEnd":696,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java#L660-L696","documentation":"makeSureStateOK() is called before state-sensitive consumer operations (e.g. pull/pop message paths) and throws unless the consumer's serviceState is RUNNING. It protects internal APIs from being used on a consumer that has not completed start() or has already been shutdown().","triggerScenarios":"Invoking message-population APIs (such as popMessage-related paths guarded by makeSureStateOK) before consumer.start() finished, after consumer.shutdown(), or while start() failed midway and left the state as CREATE_JUST/START_FAILED.","commonSituations":"Reusing a consumer instance after shutdown(); calling consumer methods from a thread before start() returned; a previous start() failure (e.g. duplicate consumer group) left the object in a non-RUNNING state; calling shutdown() during application undeploy and then issuing requests.","solutions":["Ensure consumer.start() completes before any message operations; check for exceptions from start()","Do not reuse a DefaultMQPushConsumer after shutdown(); create a fresh instance instead","If start() previously failed, inspect the earlier exception — this state error is only a symptom","Delay shutdown until all in-flight consumer API calls have drained (e.g. during graceful application stop)"],"exampleFix":"// before\nDefaultMQPushConsumer c = new DefaultMQPushConsumer(\"g\");\nc.subscribe(\"t\", \"*\");\nc.shutdown();\nc.fetchSubscribeMessageQueues(\"t\"); // state is SHUTDOWN_ALREADY\n\n// after\nDefaultMQPushConsumer c = new DefaultMQPushConsumer(\"g\");\nc.subscribe(\"t\", \"*\");\nc.start();\ntry {\n    c.fetchSubscribeMessageQueues(\"t\");\n} finally {\n    c.shutdown();\n}\n// any later need: construct a new consumer instance","handlingStrategy":"try-catch","validationCode":"// guard state before calling state-sensitive APIs\nimport org.apache.rocketmq.client.impl.consumer.DefaultMQPushConsumerImpl; // internal: prefer tracking lifecycle in your own wrapper\nif (!started.get()) throw new IllegalStateException(\"consumer not started\");","typeGuard":null,"tryCatchPattern":"try {\n    consumer.fetchSubscribeMessageQueues(topic);\n} catch (MQClientException e) {\n    if (e.getMessage().contains(\"service state not OK\")) {\n        // consumer is stopped/failed: reinitialize or skip, do not blindly retry\n        reinitConsumer();\n    } else throw e;\n}","preventionTips":["Model consumer lifecycle explicitly (NEW -> STARTED -> STOPPED) in your wrapper class","Never share a consumer across start/shutdown cycles; recreate instances","Drain in-flight calls before shutdown during graceful stop"],"tags":["rocketmq","lifecycle","consumer-state"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}