apache/rocketmq · critical · MQClientException

The consumer group[{consumerGroup}] has been created before,

Error message

The consumer group[{consumerGroup}] has been created before, specify another name please.

What it means

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.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java:750

                        case BROADCASTING:
                            this.offsetStore = new LocalFileOffsetStore(this.mQClientFactory, this.defaultMQPullConsumer.getConsumerGroup());
                            break;
                        case CLUSTERING:
                            this.offsetStore = new RemoteBrokerOffsetStore(this.mQClientFactory, this.defaultMQPullConsumer.getConsumerGroup());
                            break;
                        default:
                            break;
                    }
                    this.defaultMQPullConsumer.setOffsetStore(this.offsetStore);
                }

                this.offsetStore.load();

                boolean registerOK = mQClientFactory.registerConsumer(this.defaultMQPullConsumer.getConsumerGroup(), this);
                if (!registerOK) {
                    this.serviceState = ServiceState.CREATE_JUST;

                    throw new MQClientException("The consumer group[" + this.defaultMQPullConsumer.getConsumerGroup()
                        + "] has been created before, specify another name please." + FAQUrl.suggestTodo(FAQUrl.GROUP_NAME_DUPLICATE_URL),
                        null);
                }

                mQClientFactory.start();
                log.info("the consumer [{}] start OK", this.defaultMQPullConsumer.getConsumerGroup());
                this.serviceState = ServiceState.RUNNING;
                break;
            case RUNNING:
            case START_FAILED:
            case SHUTDOWN_ALREADY:
                throw new MQClientException("The PullConsumer service state not OK, maybe started once, "
                    + this.serviceState
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_SERVICE_NOT_OK),
                    null);
            default:
                break;
        }

View on GitHub (pinned to 293f588571)

Solutions

1. Give each consumer instance a unique consumerGroup, or ensure only one consumer per group per client instance exists
2. Call shutdown() (and await termination) on the old consumer before starting a replacement
3. In Spring, verify bean definitions for accidental duplicates and mark the consumer a singleton managed bean instead of manually constructing it
4. Check the FAQ link GROUP_NAME_DUPLICATE_URL guidance in the message

Example fix

// before
DefaultMQPullConsumer c1 = new DefaultMQPullConsumer("my-group");
DefaultMQPullConsumer c2 = new DefaultMQPullConsumer("my-group");
c1.start(); c2.start(); // throws

// after
DefaultMQPullConsumer c1 = new DefaultMQPullConsumer("my-group-a");
DefaultMQPullConsumer c2 = new DefaultMQPullConsumer("my-group-b");
c1.start(); c2.start();

// before start: ensure a new group name or prior instance shut down
if (managedConsumers.containsKey(group)) { throw new IllegalStateException("group already started: " + group); }

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• The PullConsumer service state not OK, maybe started once, {
• consumerGroup is null
• messageModel is null
• The Factory object[{clientId}] has been created before, and
• Failed to load rocksdb for auth_acl, please check whether it

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/fda1013996c01a9c. Report an issue: GitHub.