{"record":{"id":"210bf00d02de9385","repo":"apache/rocketmq","slug":"the-consumer-group","errorCode":null,"errorMessage":"The consumer group[","messagePattern":"The consumer group\\[","errorType":"exception","errorClass":"MQClientException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java","lineNumber":343,"sourceCode":"            default:\n                break;\n        }\n    }\n\n    private void initScheduledThreadPoolExecutor() {\n        this.scheduledThreadPoolExecutor = new ScheduledThreadPoolExecutor(\n                this.defaultLitePullConsumer.getPullThreadNums(),\n                new ThreadFactoryImpl(\"PullMsgThread-\" + this.defaultLitePullConsumer.getConsumerGroup())\n        );\n    }\n\n    private void initMQClientFactory() throws MQClientException {\n        this.mQClientFactory = MQClientManager.getInstance().getOrCreateMQClientInstance(this.defaultLitePullConsumer, this.rpcHook);\n        boolean registerOK = mQClientFactory.registerConsumer(this.defaultLitePullConsumer.getConsumerGroup(), this);\n        if (!registerOK) {\n            this.serviceState = ServiceState.CREATE_JUST;\n\n            throw new MQClientException(\"The consumer group[\" + this.defaultLitePullConsumer.getConsumerGroup()\n                + \"] has been created before, specify another name please.\" + FAQUrl.suggestTodo(FAQUrl.GROUP_NAME_DUPLICATE_URL),\n                null);\n        }\n    }\n\n    private void initRebalanceImpl() {\n        this.rebalanceImpl.setConsumerGroup(this.defaultLitePullConsumer.getConsumerGroup());\n        this.rebalanceImpl.setMessageModel(this.defaultLitePullConsumer.getMessageModel());\n        this.rebalanceImpl.setAllocateMessageQueueStrategy(this.defaultLitePullConsumer.getAllocateMessageQueueStrategy());\n        this.rebalanceImpl.setmQClientFactory(this.mQClientFactory);\n    }\n\n    private void initPullAPIWrapper() {\n        this.pullAPIWrapper = new PullAPIWrapper(\n            mQClientFactory,\n            this.defaultLitePullConsumer.getConsumerGroup(), isUnitMode());\n        this.pullAPIWrapper.registerFilterMessageHook(filterMessageHookList);\n    }","sourceCodeStart":325,"sourceCodeEnd":361,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java#L325-L361","documentation":"MQClientException thrown from DefaultLitePullConsumerImpl.initMQClientFactory: registerConsumer returned false because another consumer instance in the same JVM (same MQClientInstance, keyed by clientId built from IP@instanceName@unitName) already registered this consumerGroup. The state is reset to CREATE_JUST and startup aborts, with a FAQ link about duplicate group names.","triggerScenarios":"Creating and starting two DefaultLitePullConsumer (or mixing push/pull consumers) with the same consumerGroup and the same client instance name (default instanceName is often 'DEFAULT' except in unit tests). Common when programmatically creating consumers per request/thread without setting a unique instanceName.","commonSituations":"Multiple consumer beans with the same group in one Spring context; test harnesses creating many consumers (note: unit-test mode auto-suffixes instanceName, production does not); migrating code that spawns a consumer per tenant without unique instanceName; re-creating a consumer after shutdown while the old registration is still held by another reference.","solutions":["Give each consumer in the JVM a unique instanceName: consumer.setInstanceName(\"consumer-\" + n)","Reuse a single consumer instance per group instead of creating new ones","Use distinct consumerGroup names for logically distinct consumers","Ensure the old instance is fully shutdown() before creating a replacement with the same group"],"exampleFix":"// before: N consumers, same group, default instanceName\nfor (int i = 0; i < 4; i++) {\n    DefaultLitePullConsumer c = new DefaultLitePullConsumer(\"cg\");\n    c.start(); // 2nd+ fails: group already created\n}\n\n// after\nfor (int i = 0; i < 4; i++) {\n    DefaultLitePullConsumer c = new DefaultLitePullConsumer(\"cg\");\n    c.setInstanceName(\"cg-worker-\" + i);\n    c.start();\n}","handlingStrategy":"validation","validationCode":"// unique instanceName per consumer in the JVM\nint seq = COUNTER.incrementAndGet();\nDefaultLitePullConsumer c = new DefaultLitePullConsumer(group);\nc.setInstanceName(group + \"-\" + seq);","typeGuard":null,"tryCatchPattern":"try {\n    c.start();\n} catch (MQClientException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"has been created before\")) {\n        // duplicate group in JVM: set unique instanceName or reuse existing consumer\n    } else throw e;\n}","preventionTips":["Centralize consumer creation in one factory that assigns unique instanceNames","Share one consumer per group rather than creating per task","Fully shutdown() old instances before replacing them"],"tags":["rocketmq","consumer","duplicate","group","instance-name"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}