{"record":{"id":"6de11481f264927f","repo":"apache/incubator-seata","slug":"incompatible-version-format-version","errorCode":null,"errorMessage":"incompatible version format:{version}","messagePattern":"incompatible version format:(.+?)","errorType":"exception","errorClass":"IncompatibleVersionException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/protocol/Version.java","lineNumber":126,"sourceCode":"    public static boolean isAboveOrEqualVersion(String clientVersion, String divideVersion) {\n        boolean isAboveOrEqualVersion = false;\n        try {\n            isAboveOrEqualVersion = convertVersion(clientVersion) >= convertVersion(divideVersion);\n        } catch (Exception e) {\n            LOGGER.error(\"convert version error, clientVersion:{}\", clientVersion, e);\n        }\n        return isAboveOrEqualVersion;\n    }\n\n    public static long convertVersion(String version) throws IncompatibleVersionException {\n        if (StringUtils.isBlank(version)) {\n            throw new IllegalArgumentException(\"The version must not be blank.\");\n        }\n\n        String[] parts = StringUtils.split(version, '.');\n        int size = parts.length;\n        if (size > MAX_VERSION_DOT + 1) {\n            throw new IncompatibleVersionException(\"incompatible version format:\" + version);\n        }\n\n        long result = 0L;\n        int i = 1;\n        size = MAX_VERSION_DOT + 1;\n        for (String part : parts) {\n            if (StringUtils.isNumeric(part)) {\n                result += calculatePartValue(part, size, i);\n            } else {\n                String[] subParts = StringUtils.split(part, '-');\n                if (StringUtils.isNumeric(subParts[0])) {\n                    result += calculatePartValue(subParts[0], size, i);\n                }\n            }\n\n            i++;\n        }\n        return result;","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/protocol/Version.java#L108-L144","documentation":"Version.convertVersion throws IncompatibleVersionException when the version string has more than MAX_VERSION_DOT+1 dot-separated parts — the parser only understands the fixed a.b.c(.d) shape and refuses anything longer rather than silently mis-ranking it.","triggerScenarios":"convertVersion called with strings like \"1.2.3.4.5\", \"2.0.0.Final-SNAPSHOT\" shaped oddly after split, or a build metadata suffix that splits into extra segments; also invoked via isAboveOrEqualVersion, which logs and returns false on this exception.","commonSituations":"Custom client version strings embedding timestamps/build numbers in dotted form; upgrading Seata to a version whose divideVersion constant is compared against a legacy version format; third-party SDKs reporting their own dotted build ids as the seata version.","solutions":["Normalize the version to at most four numeric segments (e.g. 2.0.0 or 2.0.0.1) before comparison.","Move qualifiers to hyphen suffixes (2.0.0-SNAPSHOT), which the parser handles via the '-' split path.","In custom integrations, call Version.isAboveOrEqualVersion (which degrades safely) rather than convertVersion directly."],"exampleFix":"// before\nVersion.convertVersion(\"2.0.0.123.456\");\n// after\nVersion.convertVersion(\"2.0.0.123\");","handlingStrategy":"validation","validationCode":"static boolean parseableVersion(String v) {\n    if (v == null || v.isBlank()) return false;\n    String[] p = v.split(\"\\\\.\");\n    return p.length <= 4; // MAX_VERSION_DOT + 1\n}","typeGuard":"static OptionalLong safeConvert(String v) {\n    try { return OptionalLong.of(Version.convertVersion(v)); }\n    catch (Exception e) { return OptionalLong.empty(); }\n}","tryCatchPattern":"catch (IncompatibleVersionException e) {\n    LOG.warn(\"unparseable peer version {}, treating as unknown/oldest\", raw); // degrade, don't kill the channel\n}","preventionTips":["Publish versions as a.b.c(.d) with hyphen qualifiers only","Use isAboveOrEqualVersion for safe comparison; reserve convertVersion for trusted inputs"],"tags":["version","format","validation"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}