alibaba/canal · error · IllegalArgumentException

tag invalid: {}

Error message

tag invalid: {}

What it means

Thrown by MQUtil.checkTagWithErr() when a tag fails the checkTag() regex validation. checkTag() requires tags to match `^[0-9a-zA-Z.*]+$` — alphanumeric (both cases allowed, unlike topics), dots, and asterisks only. Spaces, hyphens, underscores, colons, and other special characters are rejected. Note that empty/null tag arrays are allowed (meaning 'no tag filtering').

Source

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

    /**
     * 检查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");
//        }

        for (String t : tags) {
            if (!checkTag(t)) {
                throw new IllegalArgumentException("tag invalid: " + t);
            }
            if (isPatternTag(t)) {
                throw new RuntimeException("pattern tag cannot multi: " + t);
            }
        }
    }
}

View on GitHub (pinned to 87be50e876)

Solutions

1. Rename tags to use only alphanumeric characters, dots, and asterisks.
2. Remove hyphens, underscores, spaces, and special characters from tag values in the canal MQ config.
3. Use camelCase or dot-separation instead of hyphens/underscores (e.g. 'orderEvent' or 'order.event' instead of 'order-event').

Example fix

// before (hyphen not allowed)
canal.mq.partitionHash=test.table:id
// tag-based routing
tag=order-created

// after (alphanumeric + dot)
tag=order.created
// or
tag=orderCreated

// Pre-validate tags before calling checkTagWithErr
if (tags != null) {
    for (String t : tags) {
        if (t != null && !t.matches("^[0-9a-zA-Z.*]+$")) {
            throw new IllegalArgumentException(
                "Tag '" + t + "' contains invalid characters. "
                + "Allowed: alphanumeric, '.', '*'");
        }
    }
}
MQUtil.checkTagWithErr(tags);

public static boolean isValidTagName(String tag) {
    return tag != null && tag.matches("^[0-9a-zA-Z.*]+$");
}

try {
    MQUtil.checkTagWithErr(tags);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("tag invalid:")) {
        logger.error("Tag name violates naming rules. Use alphanumeric, '.', '*' only.");
    }
    throw e;
}

When it happens

Trigger: Calling checkTagWithErr() with a tag containing disallowed characters — e.g. 'order-tag' (hyphen), 'order_tag' (underscore), 'order tag' (space), or 'order#1' (hash).

Common situations: MQ tag naming convention uses hyphens or underscores which are not allowed by canal's tag validator; tag was derived from a source value containing special characters; config file has a tag with trailing whitespace or newline characters.

Related errors

• topic invalid: {}
• topic cannot null
• pattern topic cannot multi: {}
• 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/90597e5dc25a6ec9. Report an issue: GitHub.