apache/rocketmq · error · MQClientException

consumerGroup is null

Error message

consumerGroup is null

What it means

checkConfig() runs at the start of consumer startup and validates the consumer group. This branch fires when getConsumerGroup() returns null. In practice Validators.checkGroup just above usually rejects null/blank groups first with its own message, so seeing this exact message means validation reached the explicit null check.

Source

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

        try {
            this.updateTopicSubscribeInfoWhenSubscriptionChanged();
            this.mQClientFactory.checkClientInBroker();
            if (this.mQClientFactory.sendHeartbeatToAllBrokerWithLock()) {
                this.mQClientFactory.rebalanceImmediately();
            }
        } 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),

View on GitHub (pinned to 293f588571)

Solutions

1. Set a non-null consumer group before start(): constructor DefaultMQPushConsumer("my-group") or setConsumerGroup(...)
2. If the group comes from config, validate the property is present at boot (fail fast on missing placeholder)
3. Disallow null in your own consumer-factory code with a precondition check

Example fix

// before
DefaultMQPushConsumer c = new DefaultMQPushConsumer(); // no group set
c.start(); // consumerGroup is null

// after
DefaultMQPushConsumer c = new DefaultMQPushConsumer("order-consumer-group");
c.start();

if (consumerGroup == null || consumerGroup.trim().isEmpty())
    throw new IllegalArgumentException("consumerGroup must be set");
DefaultMQPushConsumer c = new DefaultMQPushConsumer(consumerGroup);

When it happens

Trigger: Constructing DefaultMQPushConsumer with a null group and calling start(); a setter or DI framework injecting null (missing property placeholder) so consumerGroup stays null; calling setConsumerGroup(null) before start.

Common situations: Property placeholder not resolved (@Value('${mq.group}') missing from config); creating the consumer with the no-arg constructor and forgetting setConsumerGroup; passing a null variable from dynamic per-tenant configuration.

Related errors

• subscription group list is empty.
• group is null.
• cidAll is null or cidAll empty
• consumerGroup can not equal
• consumerGroup is null

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