apache/rocketmq · error · MQClientException

consumerGroup can not equal

Error message

consumerGroup can not equal 

What it means

MQClientException from DefaultLitePullConsumerImpl.checkConfig: the consumerGroup equals the reserved default string ("DEFAULT_CONSUMER" in MixAll.DEFAULT_CONSUMER_GROUP). Since this group is shared by anyone who forgets to configure a group, the client refuses to start with it.

Source

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

        // If assign function invoke before start function, then update pull task after initialization.
        if (subscriptionType == SubscriptionType.ASSIGN) {
            updateAssignPullTask(assignedMessageQueue.getAssignedMessageQueues());
        }

        for (String topic : topicMessageQueueChangeListenerMap.keySet()) {
            Set<MessageQueue> messageQueues = fetchMessageQueues(topic);
            messageQueuesForTopic.put(topic, messageQueues);
        }
        this.mQClientFactory.checkClientInBroker();
    }

    private void checkConfig() throws MQClientException {
        // Check consumerGroup
        Validators.checkGroup(this.defaultLitePullConsumer.getConsumerGroup());

        // Check consumerGroup name is not equal default consumer group name.
        if (this.defaultLitePullConsumer.getConsumerGroup().equals(MixAll.DEFAULT_CONSUMER_GROUP)) {
            throw new MQClientException(
                "consumerGroup can not equal "
                    + MixAll.DEFAULT_CONSUMER_GROUP
                    + ", please specify another one."
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // Check messageModel is not null.
        if (null == this.defaultLitePullConsumer.getMessageModel()) {
            throw new MQClientException(
                "messageModel is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        // Check allocateMessageQueueStrategy is not null
        if (null == this.defaultLitePullConsumer.getAllocateMessageQueueStrategy()) {
            throw new MQClientException(

View on GitHub (pinned to 293f588571)

Solutions

1. Set an explicit group: consumer.setConsumerGroup("my-order-pull-group") or new DefaultLitePullConsumer("my-order-pull-group")
2. Fail fast at config load time if the group property is blank, before constructing the consumer
3. Check for typos in property keys feeding the consumer configuration

Example fix

// before
DefaultLitePullConsumer c = new DefaultLitePullConsumer();
c.start(); // consumerGroup can not equal DEFAULT_CONSUMER

// after
DefaultLitePullConsumer c = new DefaultLitePullConsumer("order-pull-group");
c.start();

if (group == null || group.isEmpty() || "DEFAULT_CONSUMER".equals(group)) {
    throw new IllegalArgumentException("A concrete consumerGroup is required");
}
DefaultLitePullConsumer c = new DefaultLitePullConsumer(group);

When it happens

Trigger: Constructing DefaultLitePullConsumer with the no-arg or default constructor and calling start() without setConsumerGroup(...), or explicitly passing the literal default group name "DEFAULT_CONSUMER".

Common situations: Quick prototypes copied from docs that skip group configuration; property-driven configs where the group key is misspelled so the default silently applies; refactoring from push to lite-pull consumer and dropping the group argument.

Related errors

• messageModel is null
• allocateMessageQueueStrategy is null
• Long polling mode, the consumer consumerTimeoutMillisWhenSus
• Invalid ConsumeFromWhere Value
• The consumer not running, please start it first.

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