{"record":{"id":"b7d108618b059e98","repo":"apache/rocketmq","slug":"the-pullconsumer-service-state-not-ok-maybe-start-b7d108","errorCode":null,"errorMessage":"The PullConsumer service state not OK, maybe started once, {serviceState}","messagePattern":"The PullConsumer service state not OK, maybe started once, (.+?)","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java","lineNumber":762,"sourceCode":"                this.offsetStore.load();\n\n                boolean registerOK = mQClientFactory.registerConsumer(this.defaultMQPullConsumer.getConsumerGroup(), this);\n                if (!registerOK) {\n                    this.serviceState = ServiceState.CREATE_JUST;\n\n                    throw new MQClientException(\"The consumer group[\" + this.defaultMQPullConsumer.getConsumerGroup()\n                        + \"] has been created before, specify another name please.\" + FAQUrl.suggestTodo(FAQUrl.GROUP_NAME_DUPLICATE_URL),\n                        null);\n                }\n\n                mQClientFactory.start();\n                log.info(\"the consumer [{}] start OK\", this.defaultMQPullConsumer.getConsumerGroup());\n                this.serviceState = ServiceState.RUNNING;\n                break;\n            case RUNNING:\n            case START_FAILED:\n            case SHUTDOWN_ALREADY:\n                throw new MQClientException(\"The PullConsumer service state not OK, maybe started once, \"\n                    + this.serviceState\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_SERVICE_NOT_OK),\n                    null);\n            default:\n                break;\n        }\n\n    }\n\n    private void checkConfig() throws MQClientException {\n        // check consumerGroup\n        Validators.checkGroup(this.defaultMQPullConsumer.getConsumerGroup());\n\n        // consumerGroup\n        if (null == this.defaultMQPullConsumer.getConsumerGroup()) {\n            throw new MQClientException(\n                \"consumerGroup is null\"\n                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),","sourceCodeStart":744,"sourceCodeEnd":780,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java#L744-L780","documentation":"Thrown by DefaultMQPullConsumerImpl.start() when the service state is anything other than CREATE_JUST — specifically RUNNING, START_FAILED, or SHUTDOWN_ALREADY. The consumer is a one-shot state machine: start() may only transition CREATE_JUST -> RUNNING; calling start() twice or after shutdown()/a failed start is rejected.","triggerScenarios":"Calling consumer.start() a second time after it already succeeded (state RUNNING); calling start() again after a previous start() threw (state START_FAILED); calling start() after shutdown() (state SHUTDOWN_ALREADY).","commonSituations":"Reconnect logic that blindly calls start() on every connection loss; lifecycle code where start() is invoked from multiple threads; frameworks re-initializing beans without recreating the consumer object.","solutions":["Create a new DefaultMQPullConsumer instance after shutdown() instead of restarting the same one","Ensure start() is called exactly once, guarded by your own lifecycle flag or a framework @PostConstruct single invocation","If a previous start() failed, log the original cause (state will be START_FAILED) and rebuild the consumer with corrected config"],"exampleFix":"// before\nconsumer.shutdown();\nconsumer.start(); // SHUTDOWN_ALREADY -> throws\n\n// after\nconsumer.shutdown();\nconsumer = new DefaultMQPullConsumer(group);\nconsumer.setNamesrvAddr(namesrv);\nconsumer.start();","handlingStrategy":"validation","validationCode":"// guard start with your own flag\nif (started.compareAndSet(false, true)) consumer.start();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Call start() exactly once per instance","Recreate the consumer after shutdown instead of restarting","Centralize lifecycle management in one component"],"tags":["rocketmq","pull-consumer","lifecycle","startup","state-machine"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}