{"record":{"id":"bd59a69bec122684","repo":"apache/rocketmq","slug":"the-consumer-not-running-please-start-it-first","errorCode":null,"errorMessage":"The consumer not running, please start it first.","messagePattern":"The consumer not running, please start it first\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java","lineNumber":202,"sourceCode":"            }\n        }\n    }\n\n    public void executeHookAfter(final ConsumeMessageContext context) {\n        if (!this.consumeMessageHookList.isEmpty()) {\n            for (ConsumeMessageHook hook : this.consumeMessageHookList) {\n                try {\n                    hook.consumeMessageAfter(context);\n                } catch (Throwable e) {\n                    log.error(\"consumeMessageHook {} executeHookAfter exception\", hook.hookName(), e);\n                }\n            }\n        }\n    }\n\n    private void checkServiceState() {\n        if (this.serviceState != ServiceState.RUNNING) {\n            throw new IllegalStateException(NOT_RUNNING_EXCEPTION_MESSAGE);\n        }\n    }\n\n    public void updateNameServerAddr(String newAddresses) {\n        this.mQClientFactory.getMQClientAPIImpl().updateNameServerAddressList(newAddresses);\n    }\n\n    private synchronized void setSubscriptionType(SubscriptionType type) {\n        if (this.subscriptionType == SubscriptionType.NONE) {\n            this.subscriptionType = type;\n        } else if (this.subscriptionType != type) {\n            throw new IllegalStateException(SUBSCRIPTION_CONFLICT_EXCEPTION_MESSAGE);\n        }\n    }\n\n    private void updateAssignedMessageQueue(String topic, Set<MessageQueue> assignedMessageQueue) {\n        this.assignedMessageQueue.updateAssignedMessageQueue(topic, assignedMessageQueue);\n    }","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java#L184-L220","documentation":"IllegalStateException thrown by DefaultLitePullConsumerImpl.checkServiceState() when an operation requiring a RUNNING consumer (commit, seek, pause, resume, assignment updates, etc.) is invoked while the consumer is in CREATE_JUST, SHUTDOWN_ALREADY or START_FAILED state. It is a lifecycle misuse guard: the internal state machine has not reached RUNNING.","triggerScenarios":"Calling consumer.seek(...), commitSync/commitAsync, assign-related or pause/resume before consumer.start(), or after consumer.shutdown(). Also when start() failed midway (registerConsumer conflict) leaving state CREATE_JUST and the application ignores the exception and continues.","commonSituations":"Ordering bug: wiring a scheduler/REST endpoint that seeks or commits before the start() call finishes; code reuse of a consumer instance after deliberate shutdown; exception during start() swallowed so the app proceeds with a half-initialized consumer.","solutions":["Call consumer.start() and let it complete before seek/commit/pause operations","Do not reuse the instance after shutdown() — create a new DefaultLitePullConsumer","Wrap start() in try/catch and abort application startup on failure instead of continuing","Ensure seek/commit calls are issued from the same thread or after the start barrier (CountDownLatch on a started flag)","If triggered intermittently, check another thread isn't shutting the consumer down concurrently"],"exampleFix":"// before\nconsumer.subscribe(\"T\", \"*\");\nconsumer.seek(mq, 0); // IllegalStateException: not RUNNING yet\nconsumer.start();\n\n// after\nconsumer.subscribe(\"T\", \"*\");\nconsumer.start();\nconsumer.seek(mq, 0);","handlingStrategy":"validation","validationCode":"// gate state-dependent calls behind a started flag\nprivate final AtomicBoolean started = new AtomicBoolean(false);\n// after consumer.start(): started.set(true);\npublic void safeSeek(MessageQueue mq, long offset) {\n    if (!started.get()) throw new IllegalStateException(\"consumer not started\");\n    consumer.seek(mq, offset);\n}","typeGuard":null,"tryCatchPattern":"try {\n    consumer.seek(mq, offset);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"not running\")) { /* start consumer first, then retry */ }\n    else throw e;\n}","preventionTips":["Establish a start() barrier (latch/flag) before exposing seek/commit endpoints","Never reuse a consumer after shutdown()","Handle start() failures as fatal — do not continue with a CREATE_JUST instance"],"tags":["rocketmq","lifecycle","consumer","lite-pull","state"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}