{"record":{"id":"c1dbaf3a840bb16a","repo":"apache/rocketmq","slug":"setassigntag-only-can-be-called-before-start","errorCode":null,"errorMessage":"setAssignTag only can be called before start.","messagePattern":"setAssignTag only can be called before start\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java","lineNumber":592,"sourceCode":"    }\n\n    public synchronized void assign(Collection<MessageQueue> messageQueues) {\n        if (messageQueues == null || messageQueues.isEmpty()) {\n            throw new IllegalArgumentException(\"Message queues can not be null or empty.\");\n        }\n        setSubscriptionType(SubscriptionType.ASSIGN);\n        assignedMessageQueue.updateAssignedMessageQueue(messageQueues);\n        if (serviceState == ServiceState.RUNNING) {\n            updateAssignPullTask(messageQueues);\n        }\n    }\n\n    public synchronized void setSubExpressionForAssign(final String topic, final String subExpression) {\n        if (StringUtils.isBlank(subExpression)) {\n            throw new IllegalArgumentException(\"subExpression can not be null or empty.\");\n        }\n        if (serviceState != ServiceState.CREATE_JUST) {\n            throw new IllegalStateException(\"setAssignTag only can be called before start.\");\n        }\n        setSubscriptionType(SubscriptionType.ASSIGN);\n        topicToSubExpression.put(topic, subExpression);\n    }\n\n    private void maybeAutoCommit() {\n        long now = System.currentTimeMillis();\n        if (now >= nextAutoCommitDeadline) {\n            commitAll();\n            nextAutoCommitDeadline = now + defaultLitePullConsumer.getAutoCommitIntervalMillis();\n        }\n    }\n\n    public synchronized List<MessageExt> poll(long timeout) {\n        try {\n            checkServiceState();\n            if (timeout < 0) {\n                throw new IllegalArgumentException(\"Timeout must not be negative\");","sourceCodeStart":574,"sourceCodeEnd":610,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java#L574-L610","documentation":"setSubExpressionForAssign throws IllegalStateException(\"setAssignTag only can be called before start.\") when the consumer's serviceState is not CREATE_JUST — i.e. start() has already been called (RUNNING or SHUTDOWN_ALREADY). The tag expression must be baked into the subscription before the client factory builds subscriptions and starts pull tasks, hence it cannot change afterwards.","triggerScenarios":"Calling setSubExpressionForAssign(topic, expr) after consumer.start(); calling it on a consumer that was started and then shut down.","commonSituations":"Reconfiguring a long-lived consumer bean at runtime; initialization-order bug where @PostConstruct start() runs before the expression setter.","solutions":["Move the setSubExpressionForAssign call before consumer.start() in your lifecycle code","To change the filter at runtime, unsubscribe/assign again on a fresh consumer instance instead","Fix bean initialization order so configuration precedes start"],"exampleFix":"// before\nconsumer.assign(queues);\nconsumer.start();\nconsumer.setSubExpressionForAssign(topic, \"TAG_A\");\n\n// after\nconsumer.assign(queues);\nconsumer.setSubExpressionForAssign(topic, \"TAG_A\");\nconsumer.start();","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    consumer.setSubExpressionForAssign(topic, expr);\n} catch (IllegalStateException e) {\n    // started already: recreate the consumer or drop the reconfiguration\n}","preventionTips":["Order lifecycle strictly: configure (assign/set expression) -> start() -> poll()","For runtime filter changes, build a new consumer instance rather than reconfiguring"],"tags":["rocketmq","consumer","lifecycle","illegal-state"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}