apache/incubator-seata · error · IllegalArgumentException

The version must not be blank.

Error message

The version must not be blank.

What it means

Version.convertVersion parses dotted version strings into a comparable long. It throws IllegalArgumentException when the input is null, empty, or whitespace — the version metadata that should identify the peer was never set.

Source

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

    }

    public static boolean isV0(String version) {
        return !isAboveOrEqualVersion(version, VERSION_0_7_1);
    }

    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);

View on GitHub (pinned to e01f97c6db)

Solutions

1. Set the version (e.g. via Version.set, or the standard client bootstrap that populates it) before any RPC that includes version negotiation.
2. If using isAboveOrEqualVersion, note it catches this error and returns false — check the error log for 'convert version error' to find the blank side.
3. Pass a literal version like "2.0.0" in custom integrations instead of a value read from an unset property.

Example fix

// before
boolean ok = Version.isAboveOrEqualVersion(System.getProperty("app.seata.version"), "1.6.0");
// after
boolean ok = Version.isAboveOrEqualVersion("2.0.0", "1.6.0");

if (StringUtils.isBlank(version)) {
    version = "2.0.0"; // sane default, or fail loudly at config load
}
boolean above = Version.isAboveOrEqualVersion(version, "1.6.0");

boolean isUsableVersion(String v) { return v != null && !v.isBlank(); }

catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must not be blank")) { useDefaultVersionAndLog(); }
    else throw e;
}

When it happens

Trigger: convertVersion("") reached via isAboveOrEqualVersion(clientVersion, divideVersion) when one side of the comparison has a blank version — e.g. a hand-built RpcMessage missing the version header, or a custom client that never sets its version string during handshake.

Common situations: Custom/embedded Seata client code skipping the version handshake; test harnesses constructing messages directly; a proxy stripping identity headers; isAboveOrEqualVersion swallows this and logs 'convert version error', so the visible symptom is a silently false comparison.

Related errors

• incompatible version format:{version}
• 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/8fdfbac2919c06bc. Report an issue: GitHub.