apache/rocketmq · error · MQClientException

The consumer group[

Error message

The consumer group[

What it means

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.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultLitePullConsumerImpl.java:343

            default:
                break;
        }
    }

    private void initScheduledThreadPoolExecutor() {
        this.scheduledThreadPoolExecutor = new ScheduledThreadPoolExecutor(
                this.defaultLitePullConsumer.getPullThreadNums(),
                new ThreadFactoryImpl("PullMsgThread-" + this.defaultLitePullConsumer.getConsumerGroup())
        );
    }

    private void initMQClientFactory() throws MQClientException {
        this.mQClientFactory = MQClientManager.getInstance().getOrCreateMQClientInstance(this.defaultLitePullConsumer, this.rpcHook);
        boolean registerOK = mQClientFactory.registerConsumer(this.defaultLitePullConsumer.getConsumerGroup(), this);
        if (!registerOK) {
            this.serviceState = ServiceState.CREATE_JUST;

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

    private void initRebalanceImpl() {
        this.rebalanceImpl.setConsumerGroup(this.defaultLitePullConsumer.getConsumerGroup());
        this.rebalanceImpl.setMessageModel(this.defaultLitePullConsumer.getMessageModel());
        this.rebalanceImpl.setAllocateMessageQueueStrategy(this.defaultLitePullConsumer.getAllocateMessageQueueStrategy());
        this.rebalanceImpl.setmQClientFactory(this.mQClientFactory);
    }

    private void initPullAPIWrapper() {
        this.pullAPIWrapper = new PullAPIWrapper(
            mQClientFactory,
            this.defaultLitePullConsumer.getConsumerGroup(), isUnitMode());
        this.pullAPIWrapper.registerFilterMessageHook(filterMessageHookList);
    }

View on GitHub (pinned to 293f588571)

Solutions

1. Give each consumer in the JVM a unique instanceName: consumer.setInstanceName("consumer-" + n)
2. Reuse a single consumer instance per group instead of creating new ones
3. Use distinct consumerGroup names for logically distinct consumers
4. Ensure the old instance is fully shutdown() before creating a replacement with the same group

Example fix

// before: N consumers, same group, default instanceName
for (int i = 0; i < 4; i++) {
    DefaultLitePullConsumer c = new DefaultLitePullConsumer("cg");
    c.start(); // 2nd+ fails: group already created
}

// after
for (int i = 0; i < 4; i++) {
    DefaultLitePullConsumer c = new DefaultLitePullConsumer("cg");
    c.setInstanceName("cg-worker-" + i);
    c.start();
}

// unique instanceName per consumer in the JVM
int seq = COUNTER.incrementAndGet();
DefaultLitePullConsumer c = new DefaultLitePullConsumer(group);
c.setInstanceName(group + "-" + seq);

try {
    c.start();
} catch (MQClientException e) {
    if (e.getMessage() != null && e.getMessage().contains("has been created before")) {
        // duplicate group in JVM: set unique instanceName or reuse existing consumer
    } else throw e;
}

When it happens

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

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

Related errors

• The user is existed
• the specified group is blank
• the specified group[%s] is longer than group max length: %s.
• the specified group[%s] contains illegal characters, allowin
• The consumer not running, please start it first.

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