{"record":{"id":"fda1013996c01a9c","repo":"apache/rocketmq","slug":"the-consumer-group-consumergroup-has-been-creat","errorCode":null,"errorMessage":"The consumer group[{consumerGroup}] has been created before, specify another name please.","messagePattern":"The consumer group\\[(.+?)\\] has been created before, specify another name please\\.","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"critical","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java","lineNumber":750,"sourceCode":"                        case BROADCASTING:\n                            this.offsetStore = new LocalFileOffsetStore(this.mQClientFactory, this.defaultMQPullConsumer.getConsumerGroup());\n                            break;\n                        case CLUSTERING:\n                            this.offsetStore = new RemoteBrokerOffsetStore(this.mQClientFactory, this.defaultMQPullConsumer.getConsumerGroup());\n                            break;\n                        default:\n                            break;\n                    }\n                    this.defaultMQPullConsumer.setOffsetStore(this.offsetStore);\n                }\n\n                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        }","sourceCodeStart":732,"sourceCodeEnd":768,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java#L732-L768","documentation":"Thrown during DefaultMQPullConsumerImpl.start() when mQClientFactory.registerConsumer returns false, i.e. a consumer with the same consumer group is already registered in this client instance. Each MQClientInstance accepts only one consumer implementation per group; duplicates are rejected to prevent ambiguous subscription and offset handling.","triggerScenarios":"Creating and starting two DefaultMQPullConsumer (or a pull plus a push consumer) with the same consumerGroup inside the same JVM/client instance; restarting a consumer whose previous instance was not fully shutdown; mixing LitePullConsumer and DefaultMQPullConsumer under one group.","commonSituations":"Dependency-injection frameworks (Spring) creating duplicate consumer beans of the same group; hot-reload/redeploy leaks the old consumer; sharing a group name between services that happen to run in the same JVM (e.g. in tests).","solutions":["Give each consumer instance a unique consumerGroup, or ensure only one consumer per group per client instance exists","Call shutdown() (and await termination) on the old consumer before starting a replacement","In Spring, verify bean definitions for accidental duplicates and mark the consumer a singleton managed bean instead of manually constructing it","Check the FAQ link GROUP_NAME_DUPLICATE_URL guidance in the message"],"exampleFix":"// before\nDefaultMQPullConsumer c1 = new DefaultMQPullConsumer(\"my-group\");\nDefaultMQPullConsumer c2 = new DefaultMQPullConsumer(\"my-group\");\nc1.start(); c2.start(); // throws\n\n// after\nDefaultMQPullConsumer c1 = new DefaultMQPullConsumer(\"my-group-a\");\nDefaultMQPullConsumer c2 = new DefaultMQPullConsumer(\"my-group-b\");\nc1.start(); c2.start();","handlingStrategy":"validation","validationCode":"// before start: ensure a new group name or prior instance shut down\nif (managedConsumers.containsKey(group)) { throw new IllegalStateException(\"group already started: \" + group); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["One consumer instance per group per JVM","Call shutdown() before replacing consumers","Use unique group names per service"],"tags":["rocketmq","pull-consumer","duplicate-group","startup","lifecycle"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}