apache/rocketmq · error · MQClientException

consumerGroup can not equal {DEFAULT_CONSUMER_GROUP}, please

Error message

consumerGroup can not equal {DEFAULT_CONSUMER_GROUP}, please specify another one.

What it means

checkConfig() rejects the reserved default consumer group name (MixAll.DEFAULT_CONSUMER_GROUP, historically "default-consumer-group"/"default_consumer_group"-style sentinel). Using it would silently group unrelated consumers together, so the client refuses it.

Source

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

        } catch (Exception e) {
            log.warn("Start the consumer {} fail.", this.defaultMQPushConsumer.getConsumerGroup(), e);
            shutdown();
            throw e;
        }
    }

    private void checkConfig() throws MQClientException {
        Validators.checkGroup(this.defaultMQPushConsumer.getConsumerGroup());

        if (null == this.defaultMQPushConsumer.getConsumerGroup()) {
            throw new MQClientException(
                "consumerGroup is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),
                null);
        }

        if (this.defaultMQPushConsumer.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);
        }

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

        if (null == this.defaultMQPushConsumer.getConsumeFromWhere()) {
            throw new MQClientException(
                "consumeFromWhere is null"
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_PARAMETER_CHECK_URL),

View on GitHub (pinned to 293f588571)

Solutions

Choose a unique, application-specific group name (e.g. appname-consumer-group)
Remove the default value from config placeholders so a missing property fails loudly instead of falling back to the reserved name
Document per-service group naming conventions to prevent collisions

Example fix

// before
DefaultMQPushConsumer c = new DefaultMQPushConsumer(MixAll.DEFAULT_CONSUMER_GROUP);

// after
DefaultMQPushConsumer c = new DefaultMQPushConsumer("payment-service-group");

Defensive patterns

Strategy: validation

Validate before calling

if (MixAll.DEFAULT_CONSUMER_GROUP.equals(group) || group == null || group.trim().isEmpty())
    throw new IllegalArgumentException("Invalid consumer group: " + group);

Prevention

Use a per-application group naming convention (e.g. <service>-<topic>-cg)
Do not ship config defaults that fall back to the reserved group name
Add a config lint rule rejecting 'default' style group names

When it happens

Trigger: Passing the literal default group constant as your group name; a config default falling through so code ends up using the sentinel value; copying example code that used the placeholder name.

Common situations: Templates or quick-start samples that ship the default group; configuration defaults like consumerGroup: ${mq.group:default_consumer_group} where the real value is never set.

Related errors

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