{"record":{"id":"90597e5dc25a6ec9","repo":"alibaba/canal","slug":"tag-invalid","errorCode":null,"errorMessage":"tag invalid: {}","messagePattern":"tag invalid: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/com/alibaba/otter/canal/common/utils/MQUtil.java","lineNumber":90,"sourceCode":"\n    /**\n     * 检查tag有效性\n     *\n     * @param tags\n     */\n    public static void checkTagWithErr(String... tags) {\n        // 空表示不使用tag\n        if (null == tags || 0 == tags.length) {\n            return;\n        }\n\n//        if (1 == tags.length && (null == tags[0] || 0 == tags[0].trim().length())) {\n//            throw new NullPointerException(\"tag cannot null\");\n//        }\n\n        for (String t : tags) {\n            if (!checkTag(t)) {\n                throw new IllegalArgumentException(\"tag invalid: \" + t);\n            }\n            if (isPatternTag(t)) {\n                throw new RuntimeException(\"pattern tag cannot multi: \" + t);\n            }\n        }\n    }\n}\n","sourceCodeStart":72,"sourceCodeEnd":98,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/common/src/main/java/com/alibaba/otter/canal/common/utils/MQUtil.java#L72-L98","documentation":"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').","triggerScenarios":"Calling checkTagWithErr() with a tag containing disallowed characters — e.g. 'order-tag' (hyphen), 'order_tag' (underscore), 'order tag' (space), or 'order#1' (hash).","commonSituations":"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.","solutions":["Rename tags to use only alphanumeric characters, dots, and asterisks.","Remove hyphens, underscores, spaces, and special characters from tag values in the canal MQ config.","Use camelCase or dot-separation instead of hyphens/underscores (e.g. 'orderEvent' or 'order.event' instead of 'order-event')."],"exampleFix":"// before (hyphen not allowed)\ncanal.mq.partitionHash=test.table:id\n// tag-based routing\ntag=order-created\n\n// after (alphanumeric + dot)\ntag=order.created\n// or\ntag=orderCreated","handlingStrategy":"validation","validationCode":"// Pre-validate tags before calling checkTagWithErr\nif (tags != null) {\n    for (String t : tags) {\n        if (t != null && !t.matches(\"^[0-9a-zA-Z.*]+$\")) {\n            throw new IllegalArgumentException(\n                \"Tag '\" + t + \"' contains invalid characters. \"\n                + \"Allowed: alphanumeric, '.', '*'\");\n        }\n    }\n}\nMQUtil.checkTagWithErr(tags);","typeGuard":"public static boolean isValidTagName(String tag) {\n    return tag != null && tag.matches(\"^[0-9a-zA-Z.*]+$\");\n}","tryCatchPattern":"try {\n    MQUtil.checkTagWithErr(tags);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"tag invalid:\")) {\n        logger.error(\"Tag name violates naming rules. Use alphanumeric, '.', '*' only.\");\n    }\n    throw e;\n}","preventionTips":["Use camelCase or dot-separated tag names instead of hyphens or underscores.","Validate tag values in config before deploying canal MQ settings.","If tags derive from source data, sanitize them to the allowed charset before use."],"tags":["mq","tag-validation","naming-convention","config-error"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}