apache/incubator-seata · error · IllegalArgumentException

Unknown BranchType[{name}]

Error message

Unknown BranchType[{name}]

What it means

BranchType.get(String) resolves a branch type by name, case-insensitively, over the enum {AT, XA, TCC, SAGA}. It throws IllegalArgumentException when the string is not one of these — a config or annotation value misspelling.

Source

Thrown at core/src/main/java/org/apache/seata/core/model/BranchType.java:88

                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 + "]");
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

1. Use exact names: at, xa, tcc, saga (any case) with no surrounding whitespace in the config value.
2. Validate user/externally supplied branch-type strings against the known set before passing them to BranchType.get.
3. Trim strings and reject unknown values early at config load with a clear message.

Example fix

# before
seata.data-source-proxy.branch-type=AT_MODE
# after
seata.data-source-proxy.branch-type=AT

static final Set<String> BRANCH_NAMES =
    Arrays.stream(BranchType.values()).map(b -> b.name().toLowerCase()).collect(Collectors.toSet());
boolean ok = BRANCH_NAMES.contains(cfgValue.trim().toLowerCase());

static Optional<BranchType> parseBranch(String s) {
    String n = s == null ? "" : s.trim();
    return Arrays.stream(BranchType.values()).filter(b -> b.name().equalsIgnoreCase(n)).findFirst();
}

When it happens

Trigger: Configuring branch type by string with a typo or unsupported alias: 'tcc ' trailing space, 'At' works but 'AT_MODE', 'at-mode', 'saga' on a very old build without SAGA, or 'xa-mode' style values from other frameworks.

Common situations: YAML/properties copy-paste errors, values borrowed from non-Seata transaction frameworks, or reflective code passing annotation attributes straight through without validation.

Related errors

• Unknown BranchType[{ordinal}]
• Unknown BranchType[{name}]
• not support config type:
• not support config data type type: %s
• unknown codec:{name}

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