alibaba/canal · error · RuntimeException

pattern topic cannot multi: {}

Error message

pattern topic cannot multi: {}

What it means

Thrown by MQUtil.checkTopicWithErr() in the multi-topic loop when a topic is detected as a pattern topic (via isPatternTopic()) while multiple topics are specified. isPatternTopic() returns true if the topic contains any character outside `^[0-9a-z:/-]+$` — notably, topics containing `*` (wildcard) are considered pattern topics. Canal does not allow combining pattern subscription with multiple explicit topics because the semantics would be ambiguous.

Source

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

    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) {
        // 空表示不使用tag
        if (null == tags || 0 == tags.length) {
            return;
        }

//        if (1 == tags.length && (null == tags[0] || 0 == tags[0].trim().length())) {
//            throw new NullPointerException("tag cannot null");
//        }

View on GitHub (pinned to 87be50e876)

Solutions

1. Use either a single pattern topic OR multiple explicit topics — never both together.
2. If a wildcard is needed, use only one topic entry containing the pattern.
3. Replace wildcard topics with explicit topic names if multiple topics are required.

Example fix

// before — mixing pattern and explicit topics
canal.mq.topic=orders,order-*,payments

// after — choose one approach
// option A: single pattern topic
canal.mq.topic=order-*
// option B: all explicit topics
canal.mq.topic=orders,order-created,order-updated,payments

// Detect pattern topics before calling checkTopicWithErr
if (topics.length > 1) {
    for (String t : topics) {
        // isPatternTopic: contains chars outside [0-9a-z:/-]
        if (!t.matches("^[0-9a-z:/-]+$")) {
            throw new IllegalArgumentException(
                "Pattern topic '" + t + "' cannot be combined with multiple topics");
        }
    }
}
MQUtil.checkTopicWithErr(topics);

public static boolean isPatternTopic(String topic) {
    return topic != null && !topic.matches("^[0-9a-z:/-]+$");
}

public static boolean isSafeMultiTopic(String... topics) {
    if (topics == null || topics.length <= 1) return true;
    for (String t : topics) {
        if (isPatternTopic(t)) return false;
    }
    return true;
}

try {
    MQUtil.checkTopicWithErr(topics);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("pattern topic cannot multi:")) {
        logger.error("Cannot mix pattern topics with multiple topics. Use one or the other.");
    }
    throw e;
}

When it happens

Trigger: Calling checkTopicWithErr() with more than one topic where at least one contains wildcard/pattern characters (asterisk, dot, or other non-literal chars) — e.g. passing both 'orders' and 'order-*'.

Common situations: Configuring canal MQ to subscribe to multiple topics where one uses a wildcard pattern; mixing explicit topic names with pattern subscriptions in the same producer; misunderstanding that `*` in a topic name triggers pattern mode.

Related errors

• topic cannot null
• topic invalid: {}
• tag invalid: {}
• Target column: {targetColumnName} not matched
• No tablestore adapter found for config key: {key}

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