apache/rocketmq · error · MQClientException

The specified topic is longer than topic max length %d.

Error message

The specified topic is longer than topic max length %d.

What it means

Validators.checkTopic rejects topics longer than TOPIC_MAX_LENGTH (127 characters). Topic length is capped because it is stored in the broker's topic config and appears in commit-log/message-queue metadata; the constant is shared with TopicValidator.

Source

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

        if (msg.getBody().length > defaultMQProducer.getMaxMessageSize()) {
            throw new MQClientException(ResponseCode.MESSAGE_ILLEGAL,
                "the message body size over max value, MAX: " + defaultMQProducer.getMaxMessageSize());
        }

        String lmqPath = msg.getUserProperty(MessageConst.PROPERTY_INNER_MULTI_DISPATCH);
        if (StringUtils.contains(lmqPath, File.separator)) {
            throw new MQClientException(ResponseCode.MESSAGE_ILLEGAL,
                "INNER_MULTI_DISPATCH " + lmqPath + " can not contains " + File.separator + " character");
        }
    }

    public static void checkTopic(String topic) throws MQClientException {
        if (UtilAll.isBlank(topic)) {
            throw new MQClientException("The specified topic is blank", null);
        }

        if (topic.length() > TOPIC_MAX_LENGTH) {
            throw new MQClientException(
                String.format("The specified topic is longer than topic max length %d.", TOPIC_MAX_LENGTH), null);
        }

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

    public static void isSystemTopic(String topic) throws MQClientException {
        if (TopicValidator.isSystemTopic(topic)) {
            throw new MQClientException(
                    String.format("The topic[%s] is conflict with system topic.", topic), null);
        }
    }

    public static void isNotAllowedSendTopic(String topic) throws MQClientException {

View on GitHub (pinned to 293f588571)

Solutions

1. Shorten the topic to <=127 characters using abbreviations or a tenant-id mapping table.
2. Hash long suffixes and keep the readable prefix within budget.
3. Assert topic.length() <= 127 in the topic-factory code path.

Example fix

// before
String topic = "evt-" + tenantId + '-' + UUID.randomUUID(); // can exceed 127

// after
String topic = "evt-" + tenantId + '-' + shortHash(tenantId); // bounded length

static boolean topicLengthOk(String topic) {
    return topic != null && topic.length() <= 127;
}

When it happens

Trigger: Programmatically building a topic from a template (app + env + tenant + event type) whose concatenation exceeds 127 chars; dynamic per-entity topics with UUID suffixes.

Common situations: Multi-tenant systems minting one topic per tenant with long tenant identifiers; namespaced topic conventions ported from systems without length limits.

Related errors

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

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