apache/rocketmq · error · MQClientException

the specified group[%s] is longer than group max length: %s.

Error message

the specified group[%s] is longer than group max length: %s.

What it means

Validators.checkGroup rejects group names longer than 120 characters. The 120 limit exists because the group is embedded into generated topic names (%RETRY%group / %DLQ%group), which must stay within the broker's topic length ceiling (127).

Source

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

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
        Validators.checkTopic(msg.getTopic());
        Validators.isNotAllowedSendTopic(msg.getTopic());

        // body

View on GitHub (pinned to 293f588571)

Solutions

Shorten the group to <=120 characters (use an abbreviation scheme for env/region suffixes).
Add a unit test asserting generated group names stay under Validators.GROUP_MAX_LENGTH.
Hash or truncate deterministic long identifiers when composing group names.

Example fix

// before
String group = appName + '-' + env + '-' + UUID.randomUUID().toString(); // often > 120

// after
String group = appName + '-' + env + '-' + Integer.toHexString(hash).substring(0, 8);

Defensive patterns

Strategy: validation

Validate before calling

static void assertGroupLength(String group) {
    if (group != null && group.length() > 120) {
        throw new IllegalArgumentException("group exceeds 120 chars: " + group.length());
    }
}

Prevention

Add a unit test bounding generated group names to 120 chars.
Avoid embedding UUIDs in group names.
Remember group length is capped because of %RETRY%/%DLQ% topic-name composition.

When it happens

Trigger: Passing a group string built by concatenating app + env + instance + UUID that exceeds 120 chars; programmatically generated group names in multi-tenant systems.

Common situations: Auto-generated group names that append suffixes (env, region, version) until they cross 120; migrating from another MQ where longer consumer names were allowed.

Related errors

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