What causes "the specified group is blank" in apache/rocketmq?

Set a non-blank group name: producer.setDefaultTopicQueueNums aside, call producer.setProducerGroup('my-group') / consumer.setConsumerGroup('my-group') before start().

apache/rocketmq · error · MQClientException

the specified group is blank

Error message

the specified group is blank

What it means

Validators.checkGroup rejects a consumer/producer group name that is null, empty, or whitespace-only. The group name is mandatory because RocketMQ builds internal retry/DLQ topic names from it. Thrown as MQClientException with no response code at client-side validation time, before any network call.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/Validators.java:52

/**
 * Common Validator
 */
public class Validators {
    public static final int CHARACTER_MAX_LENGTH = 255;
    public static final int TOPIC_MAX_LENGTH = 127;
    /*
     * Group name max length is 120, for it will be used to make up retry and DLQ topic,
     * like pull retry: %RETRY%group_topic and pop retry: %RETRY%group_topic.
     */
    public static final int GROUP_MAX_LENGTH = 120;

    /**
     * Validate group
     */
    public static void checkGroup(String group) throws MQClientException {
        if (UtilAll.isBlank(group)) {
            throw new MQClientException("the specified group is blank", null);
        }

        if (group.length() > GROUP_MAX_LENGTH) {
            throw new MQClientException(String.format("the specified group[%s] is longer than group max length: %s.", group, GROUP_MAX_LENGTH), null);
        }

        if (isTopicOrGroupIllegal(group)) {
            throw new MQClientException(String.format(
                    "the specified group[%s] contains illegal characters, allowing only %s", group,
                    "^[%|a-zA-Z0-9_-]+$"), null);
        }
    }

    public static void checkMessage(Message msg, DefaultMQProducer defaultMQProducer) throws MQClientException {
        if (null == msg) {
            throw new MQClientException(ResponseCode.MESSAGE_ILLEGAL, "the message is null");
        }
        // topic

View on GitHub (pinned to 293f588571)

Solutions

Set a non-blank group name: producer.setDefaultTopicQueueNums aside, call producer.setProducerGroup('my-group') / consumer.setConsumerGroup('my-group') before start().
If the group comes from config, add a startup assertion or fail-fast check that the property is present.
Use distinct names per logical service so retry/DLQ topics (%RETRY%group, %DLQ%group) do not collide.

Example fix

// before
DefaultMQPushConsumer c = new DefaultMQPushConsumer(null);

// after
DefaultMQPushConsumer c = new DefaultMQPushConsumer("order-service-consumer");

Defensive patterns

Strategy: validation

Validate before calling

static String requireGroup(String group) {
    if (group == null || group.isBlank()) {
        throw new IllegalArgumentException("consumer/producer group must be configured");
    }
    return group;
}

Prevention

Fail fast at startup on blank group config instead of during first send/subscribe.
Use @ConfigurationProperties with validated (non-null) fields for group names.
Give each service a stable, documented group name.

When it happens

Trigger: Constructing DefaultMQProducer/consumer with a null or '' group name, or setting consumer group via a property/config that resolves to blank (missing env var, empty YAML value) — checkGroup runs during client startup or subscribe/send.

Common situations: Spring Boot @Value('${rocketmq.consumer.group}') that resolves empty because the property is undefined; copy-paste producer templates that drop setConsumerGroup; tests constructing clients inline.

Related errors

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