apache/incubator-seata · error · IllegalArgumentException

Unknown BranchType[{name}]

Error message

Unknown BranchType[{name}]

What it means

Compatible-layer BranchType.get(String): resolves a branch type by (case-insensitive) name and throws when no constant matches. Any typo or future/legacy name outside AT/TCC/SAGA/XA is rejected.

Source

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

                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() {
        return org.apache.seata.core.model.BranchType.get(this.name());
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

1. Correct the name to exactly one of: AT, TCC, SAGA, XA (case-insensitive, no whitespace).
2. Trim and validate the value before passing it in.
3. Upgrade the compatible module if the name is a legitimately new branch type.

Example fix

# before (state machine / config)
"Type": "AT "
"type": "at_mode"

# after
"Type": "AT"
"type": "AT"

private static final Set<String> VALID = Set.of("AT", "TCC", "SAGA", "XA");

String normalized = name == null ? "" : name.trim().toUpperCase();
if (!VALID.contains(normalized)) {
    throw new IllegalArgumentException("branch type must be one of " + VALID + ": " + name);
}
return BranchType.get(normalized);

boolean isValidBranchTypeName(String name) {
    if (name == null) return false;
    for (io.seata.core.model.BranchType t : io.seata.core.model.BranchType.values()) {
        if (t.name().equalsIgnoreCase(name.trim())) return true;
    }
    return false;
}

try {
    return BranchType.get(name);
} catch (IllegalArgumentException e) {
    throw new ConfigurationException("unknown branch type '" + name + "'; expected AT/TCC/SAGA/XA", e);
}

When it happens

Trigger: Calling BranchType.get(name) with a string like 'at ' (trailing space), 'At' works but 'AT_MODE', 'tcc2', or an empty string does not; also names introduced by newer versions that this build does not know.

Common situations: Config files or JSON state-machine definitions with misspelled branch type names; whitespace from config interpolation; version skew where a peer sends a new branch type name.

Related errors

• not support config type:
• unknown lock mode:{}
• unknown session mode:{}
• unknown store mode:{}
• could not convert '{size}' to byte length

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