apache/rocketmq · error · MQClientException

consumerGroup is null

Error message

consumerGroup is null

What it means

Thrown by checkConfig() during start() when the consumer group is null. Note Validators.checkGroup runs first and usually throws its own error for null; this explicit check exists as a belt-and-braces guard. The consumer group identifies the subscription and offset-tracking identity and must be set before start.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java:778

            case START_FAILED:
            case SHUTDOWN_ALREADY:
                throw new MQClientException("The PullConsumer service state not OK, maybe started once, "
                    + this.serviceState
                    + FAQUrl.suggestTodo(FAQUrl.CLIENT_SERVICE_NOT_OK),
                    null);
            default:
                break;
        }

    }

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

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

        // consumerGroup
        if (this.defaultMQPullConsumer.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);
        }

        // messageModel
        if (null == this.defaultMQPullConsumer.getMessageModel()) {
            throw new MQClientException(

View on GitHub (pinned to 293f588571)

Solutions

1. Set a non-null consumer group before start(): consumer.setConsumerGroup("my-group")
2. Validate required config at application startup and fail fast with a clear message when the group property is missing
3. Prefer the parameterized constructor DefaultMQPullConsumer(consumerGroup) so the group cannot be forgotten

Example fix

// before
DefaultMQPullConsumer consumer = new DefaultMQPullConsumer();
consumer.start(); // group still null

// after
DefaultMQPullConsumer consumer = new DefaultMQPullConsumer("my-consumer-group");
consumer.setNamesrvAddr(namesrv);
consumer.start();

if (group == null || group.trim().isEmpty()) throw new IllegalStateException("consumer group must be configured");

When it happens

Trigger: Constructing DefaultMQPullConsumer with the no-arg constructor and never calling setConsumerGroup(...) before start(); passing null explicitly: new DefaultMQPullConsumer(null); a config property binding that silently leaves the group unset.

Common situations: Property placeholder not resolved (e.g. ${rocketmq.consumer.group} missing from environment), so the setter receives null; code copied from examples that assume a constructor argument that was removed.

Related errors

• consumerGroup can not equal {DEFAULT_CONSUMER_GROUP}, please
• messageModel is null
• The consumer group[{consumerGroup}] has been created before,
• The PullConsumer service state not OK, maybe started once, {
• allocateMessageQueueStrategy is null

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