apache/incubator-seata · error · IncompatibleVersionException

incompatible version format:{version}

Error message

incompatible version format:{version}

What it means

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.

Source

Thrown at core/src/main/java/org/apache/seata/core/protocol/Version.java:126

    public static boolean isAboveOrEqualVersion(String clientVersion, String divideVersion) {
        boolean isAboveOrEqualVersion = false;
        try {
            isAboveOrEqualVersion = convertVersion(clientVersion) >= convertVersion(divideVersion);
        } catch (Exception e) {
            LOGGER.error("convert version error, clientVersion:{}", clientVersion, e);
        }
        return isAboveOrEqualVersion;
    }

    public static long convertVersion(String version) throws IncompatibleVersionException {
        if (StringUtils.isBlank(version)) {
            throw new IllegalArgumentException("The version must not be blank.");
        }

        String[] parts = StringUtils.split(version, '.');
        int size = parts.length;
        if (size > MAX_VERSION_DOT + 1) {
            throw new IncompatibleVersionException("incompatible version format:" + version);
        }

        long result = 0L;
        int i = 1;
        size = MAX_VERSION_DOT + 1;
        for (String part : parts) {
            if (StringUtils.isNumeric(part)) {
                result += calculatePartValue(part, size, i);
            } else {
                String[] subParts = StringUtils.split(part, '-');
                if (StringUtils.isNumeric(subParts[0])) {
                    result += calculatePartValue(subParts[0], size, i);
                }
            }

            i++;
        }
        return result;

View on GitHub (pinned to e01f97c6db)

Solutions

1. Normalize the version to at most four numeric segments (e.g. 2.0.0 or 2.0.0.1) before comparison.
2. Move qualifiers to hyphen suffixes (2.0.0-SNAPSHOT), which the parser handles via the '-' split path.
3. In custom integrations, call Version.isAboveOrEqualVersion (which degrades safely) rather than convertVersion directly.

Example fix

// before
Version.convertVersion("2.0.0.123.456");
// after
Version.convertVersion("2.0.0.123");

static boolean parseableVersion(String v) {
    if (v == null || v.isBlank()) return false;
    String[] p = v.split("\\.");
    return p.length <= 4; // MAX_VERSION_DOT + 1
}

static OptionalLong safeConvert(String v) {
    try { return OptionalLong.of(Version.convertVersion(v)); }
    catch (Exception e) { return OptionalLong.empty(); }
}

catch (IncompatibleVersionException e) {
    LOG.warn("unparseable peer version {}, treating as unknown/oldest", raw); // degrade, don't kill the channel
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The version must not be blank.
• Two or more start states, ${target} and ${definitions.StartS
• URL must not be null or blank
• ip and port string cannot be empty!
• "pageNum range not in [" + MIN_PAGE_NUM + "-" + MAX_PAGE_NUM

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/6de11481f264927f. Report an issue: GitHub.