alibaba/canal · error · RuntimeException

topic invalid

Error message

topic invalid: {}

What it means

Thrown by MQUtil.checkTopicWithErr() in the single-topic branch when the topic fails the checkTopic() regex validation. checkTopic() requires topics to match `^[0-9a-z:/.*-]+$` — only lowercase letters, digits, colons, slashes, dots, asterisks (for pattern topics), and hyphens. Uppercase letters, spaces, and most special characters are rejected. The exception type is RuntimeException.

Solutions

1. Rename the topic to use only lowercase alphanumeric, colons, slashes, dots, asterisks, and hyphens.
2. If using Kafka, note that Kafka topics allow more characters but canal's MQUtil enforces a stricter subset.
3. Remove any whitespace, underscores, or uppercase letters from the topic name in canal.mq.topic.

Example fix

// before (uppercase + underscore)
canal.mq.topic=Order_Events

// after (lowercase, hyphen)
canal.mq.topic=order-events

// Pre-validate the topic against the allowed charset before calling checkTopicWithErr
String topic = topics[0];
if (topic == null || !topic.matches("^[0-9a-z:/.*-]+$")) {
    throw new IllegalArgumentException(
        "Topic '" + topic + "' contains invalid characters. "
        + "Allowed: lowercase a-z, digits, ':', '/', '.', '*', '-'");
}
MQUtil.checkTopicWithErr(topic);

// Type guard for valid single-topic naming
public static boolean isValidTopicName(String topic) {
    return topic != null && topic.matches("^[0-9a-z:/.*-]+$");
}

try {
    MQUtil.checkTopicWithErr(topic);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("topic invalid:")) {
        logger.error("Topic name '{}' violates naming rules. Use lowercase alphanumeric, ':', '/', '.', '*', '-'.");
    }
    throw e;
}

When it happens

Trigger: Calling checkTopicWithErr() with exactly one topic that fails the regex — e.g. contains uppercase letters (MyTopic), spaces (my topic), underscores (my_topic), or special characters not in the allowed set.

Common situations: Topic name uses camelCase or uppercase; topic contains underscores (common in some naming conventions); trailing whitespace from config files; copy-paste from a URL-encoded topic name.

Related errors

• pattern topic cannot multi
• tag invalid
• topic cannot null
• dbMapping.database
• dbMapping.table

AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14). Data as JSON: /api/errors/4e8f8da9f0c04767. Report an issue: GitHub.

Appendix: source

Thrown at common/src/main/java/com/alibaba/otter/canal/common/utils/MQUtil.java:60

        return !tag.matches("^[0-9a-zA-Z]+$");
    }

    /**
     * 检查topic有效性
     *
     * @param topics
     */
    public static void checkTopicWithErr(String... topics) {
        if (null == topics || 0 == topics.length) {
            throw new NullPointerException("topic cannot null");
        }

        if (1 == topics.length) {
            boolean ok = checkTopic(topics[0]);
            if (ok) {
                return;
            }
            throw new RuntimeException("topic invalid: " + topics[0]);
        }

        for (String t : topics) {
            if (!checkTopic(t)) {
                throw new IllegalArgumentException("topic invalid: " + t);
            }
            if (isPatternTopic(t)) {
                throw new RuntimeException("pattern topic cannot multi: " + t);
            }
        }
    }

    /**
     * 检查tag有效性
     *
     * @param tags
     */
    public static void checkTagWithErr(String... tags) {

View on GitHub (pinned to 87be50e876)