apache/rocketmq · error · MQClientException

the specified group[%s] contains illegal characters, allowin

Error message

the specified group[%s] contains illegal characters, allowing only %s

What it means

Validators.checkGroup rejects group names containing characters outside [%|a-zA-Z0-9_-] (the regex check is isTopicOrGroupIllegal). Percent is tolerated, but spaces, dots, colons, slashes, CJK, and other symbols make the name illegal because it is used to compose retry/DLQ topic names.

Source

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

     * 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
        if (null == msg.getBody()) {
            throw new MQClientException(ResponseCode.MESSAGE_ILLEGAL, "the message body is null");
        }

View on GitHub (pinned to 293f588571)

Solutions

1. Restrict the group to letters, digits, underscore, hyphen (and % only if intentionally).
2. Replace dots/spaces with hyphens: 'order.service prod' -> 'order-service-prod'.
3. Add a config-time regex assertion: group.matches("^[%|a-zA-Z0-9_-]+$") before client start.

Example fix

// before
consumer.setConsumerGroup("order.service.prod");

// after
consumer.setConsumerGroup("order-service-prod");

private static final Pattern LEGAL = Pattern.compile("^[%|a-zA-Z0-9_-]+$");

static boolean legalGroupName(String g) {
    return g != null && LEGAL.matcher(g).matches();
}

When it happens

Trigger: Calling setConsumerGroup/setProducerGroup (or the constructor) with names containing '.', ' ', ':', '/', '#', unicode, etc.; group names sourced from URLs or free-text fields.

Common situations: Using hostname or FQDN as the group; injecting a group with spaces from a properties file; names with dots (common when reusing Kafka consumer-group conventions).

Related errors

• the specified group is blank
• the specified group[%s] is longer than group max length: %s.
• The specified topic[%s] contains illegal characters, allowin
• The topic[%s] is conflict with system topic.
• 208

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