apache/incubator-seata · error · IllegalArgumentException

Unknown BranchType[{ordinal}]

Error message

Unknown BranchType[{ordinal}]

What it means

Compatible-layer BranchType.get(int): looks up a branch type by ordinal and throws when no constant matches. Branch types are AT, TCC, SAGA, XA; any other integer (from a foreign version or bad data) is rejected.

Source

Thrown at compatible/src/main/java/io/seata/core/model/BranchType.java:70

     * @return the branch type
     */
    public static BranchType get(byte ordinal) {
        return get((int) ordinal);
    }

    /**
     * Get branch type.
     *
     * @param ordinal the ordinal
     * @return the branch type
     */
    public static BranchType get(int ordinal) {
        for (BranchType branchType : values()) {
            if (branchType.ordinal() == ordinal) {
                return branchType;
            }
        }
        throw new IllegalArgumentException("Unknown BranchType[" + ordinal + "]");
    }

    /**
     * Get branch type.
     *
     * @param name the name
     * @return the branch type
     */
    public static BranchType get(String name) {
        for (BranchType branchType : values()) {
            if (branchType.name().equalsIgnoreCase(name)) {
                return branchType;
            }
        }
        throw new IllegalArgumentException("Unknown BranchType[" + name + "]");
    }

    public org.apache.seata.core.model.BranchType convertBranchType() {

View on GitHub (pinned to e01f97c6db)

Solutions

1. Pin client, server, and compatible module to the same Seata release.
2. Use BranchType.get(name) (the String overload) instead of ordinals — names are stable across versions.
3. Inspect and repair any stored branch records containing invalid type codes.
4. Range-check the ordinal before conversion.

Example fix

// before (ordinal is version-fragile)
org.apache.seata.core.model.BranchType t =
        io.seata.core.model.BranchType.get(rawOrdinal).convertBranchType();

// after (name-based, stable)
org.apache.seata.core.model.BranchType t =
        org.apache.seata.core.model.BranchType.get(branchTypeNameString);

boolean isKnownBranchType(int ordinal) {
    for (io.seata.core.model.BranchType t : io.seata.core.model.BranchType.values()) {
        if (t.ordinal() == ordinal) return true;
    }
    return false;
}

try {
    return BranchType.get(ordinal);
} catch (IllegalArgumentException e) {
    LOGGER.warn("unknown branch type ordinal {}", ordinal);
    return BranchType.AT; // or quarantine the record
}

When it happens

Trigger: Calling BranchType.get(ordinal) with an int outside the declared constants — during conversion of an io.seata BranchType to org.apache.seata BranchType (convertBranchType path), or when decoding branch records whose type code came from a mismatched build.

Common situations: Rolling upgrades between Seata versions that added/reordered BranchType constants; io.seata compatible shim used against a newer server; corrupted branch_table rows; hardcoded numeric branch types in scripts.

Related errors

• Unknown TransactionExceptionCode[{ordinal}]
• Unknown GlobalStatus[{code}]
• Cannot convert {name}
• Cannot convert {name}
• Cannot convert {name}

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