apache/rocketmq · error · 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

During start(), after services are booted the consumer tries mQClientFactory.registerConsumer(consumerGroup, this). If a consumer with the same group is already registered in this client instance (the shared MQClientInstance), registerOK is false; the code rolls back its own state to CREATE_JUST, shuts down the consume service, and throws with the GROUP_NAME_DUPLICATE FAQ hint.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPushConsumerImpl.java:992

                    this.consumeMessagePopService = new ConsumeMessagePopOrderlyService(this, (MessageListenerOrderly) this.getMessageListenerInner());
                } else if (this.getMessageListenerInner() instanceof MessageListenerConcurrently) {
                    this.consumeOrderly = false;
                    this.consumeMessageService =
                        new ConsumeMessageConcurrentlyService(this, (MessageListenerConcurrently) this.getMessageListenerInner());
                    //POPTODO reuse Executor ?
                    this.consumeMessagePopService =
                        new ConsumeMessagePopConcurrentlyService(this, (MessageListenerConcurrently) this.getMessageListenerInner());
                }

                this.consumeMessageService.start();
                // POPTODO
                this.consumeMessagePopService.start();

                boolean registerOK = mQClientFactory.registerConsumer(this.defaultMQPushConsumer.getConsumerGroup(), this);
                if (!registerOK) {
                    this.serviceState = ServiceState.CREATE_JUST;
                    this.consumeMessageService.shutdown(defaultMQPushConsumer.getAwaitTerminationMillisWhenShutdown());
                    throw new MQClientException("The consumer group[" + this.defaultMQPushConsumer.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.defaultMQPushConsumer.getConsumerGroup());
                this.serviceState = ServiceState.RUNNING;
                break;
            case RUNNING:
            case START_FAILED:
            case SHUTDOWN_ALREADY:
                throw new MQClientException("The PushConsumer 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 in the same JVM a unique instanceName (consumer.setInstanceName(...)) so they get separate MQClientInstance objects
2. Ensure the old consumer is fully shutdown() before starting a replacement; in Spring use destroy-method and avoid duplicate component scanning
3. If both consumers legitimately share a group, they must also share the same MQClientInstance — instead use ONE consumer instance, not two
4. Check for duplicate bean definitions / config files instantiating the consumer twice

Example fix

// before
DefaultMQPushConsumer c1 = new DefaultMQPushConsumer("order-group"); c1.start();
DefaultMQPushConsumer c2 = new DefaultMQPushConsumer("order-group"); c2.start(); // same clientId -> exception

// after
DefaultMQPushConsumer c2 = new DefaultMQPushConsumer("order-group");
c2.setInstanceName("order-group-consumer-2"); // distinct MQClientInstance
c2.start();

// ensure a group is registered at most once per client instance before starting
MQClientInstance factory = ...; // internal; in practice: track groups in your app
if (registeredGroups.add(consumerGroup)) { consumer.start(); }
else throw new IllegalStateException("group already started in this JVM: " + consumerGroup);

try {
    consumer.start();
} catch (MQClientException e) {
    if (e.getMessage().contains("has been created before")) {
        // pick unique instanceName or unique group, rebuild consumer, retry once
    } else throw e;
}

When it happens

Trigger: Starting two DefaultMQPushConsumer objects with the same consumerGroup within one JVM/client instance (same clientId: ip@instanceName@unitName); restarting a consumer whose shutdown did not fully unregister it; same instanceName reused for multiple consumers.

Common situations: Hot-reload or Spring context refresh creating a second consumer with the same group and same instanceName; embedding two consumer beans reading the same group; a previous shutdown() that did not complete unregisterConsumer so the factory still holds the group.

Related errors

• The user is existed
• subscription group is null.
• subscription group list is empty.
• subscription group config is null.
• group is null.

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