{"record":{"id":"f39bece4bbfb26e4","repo":"apache/incubator-seata","slug":"the-default-branch-type-must-be-at-or-xa-the-valu","errorCode":null,"errorMessage":"The default branch type must be AT or XA. the value of the argument is: {defaultBranchType}","messagePattern":"The default branch type must be AT or XA\\. the value of the argument is: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/context/RootContext.java","lineNumber":98,"sourceCode":"     */\n    public static final String HIDDEN_KEY_BRANCH_TYPE = Constants.HIDE_KEY_PREFIX_CHAR + KEY_BRANCH_TYPE;\n\n    /**\n     * The constant KEY_GLOBAL_LOCK_FLAG, VALUE_GLOBAL_LOCK_FLAG\n     */\n    public static final String KEY_GLOBAL_LOCK_FLAG = \"TX_LOCK\";\n\n    public static final Boolean VALUE_GLOBAL_LOCK_FLAG = true;\n\n    private static ContextCore CONTEXT_HOLDER = ContextCoreLoader.load();\n\n    private static BranchType DEFAULT_BRANCH_TYPE;\n\n    public static final String KEY_COMBINE_TRANSACTION_FLAG = \"TX_COMBINE\";\n\n    public static void setDefaultBranchType(BranchType defaultBranchType) {\n        if (defaultBranchType != AT && defaultBranchType != XA) {\n            throw new IllegalArgumentException(\"The default branch type must be \" + AT + \" or \" + XA + \".\"\n                    + \" the value of the argument is: \" + defaultBranchType);\n        }\n        if (DEFAULT_BRANCH_TYPE != null && DEFAULT_BRANCH_TYPE != defaultBranchType && LOGGER.isWarnEnabled()) {\n            LOGGER.warn(\n                    \"The `{}.DEFAULT_BRANCH_TYPE` has been set repeatedly. The value changes from {} to {}\",\n                    RootContext.class.getSimpleName(),\n                    DEFAULT_BRANCH_TYPE,\n                    defaultBranchType);\n        }\n        DEFAULT_BRANCH_TYPE = defaultBranchType;\n    }\n\n    /**\n     * Gets xid.\n     *\n     * @return the xid\n     */\n    @Nullable","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/context/RootContext.java#L80-L116","documentation":"RootContext.setDefaultBranchType rejects any BranchType other than AT or XA. The default branch type is what getBranchType() falls back to when a binding is absent, and only resource-managed branch modes (AT/XA) are valid defaults — TCC and SAGA are always explicitly bound by their interceptors, so they cannot be defaults.","triggerScenarios":"Calling RootContext.setDefaultBranchType(BranchType.TCC) or (SAGA) programmatically, or configuring the client default branch type property as 'TCC'/'SAGA' which is read at startup and pushed into this method.","commonSituations":"Team sets seata.client.default-branch-type=tcc believing it will make @TwoPhaseBusiness methods behave like a default, or migrates a config where branch type semantics were misunderstood; also custom bootstrap code that copies an explicit bind into the default.","solutions":["Use only AT or XA for the default branch type: seata.client.default-branch-type=at (or xa).","For TCC/SAGA participation, let the @TwoPhaseBusiness/@GlobalTransactional-type annotations and interceptors bind the branch type explicitly; do not set it as default.","Remove custom calls to setDefaultBranchType with non-AT/XA values."],"exampleFix":"# before\nseata.client.default-branch-type=tcc\n# after\nseata.client.default-branch-type=xa","handlingStrategy":"validation","validationCode":"BranchType t = BranchType.get(cfgValue);\nif (t != BranchType.AT && t != BranchType.XA) {\n    throw new ConfigException(\"default-branch-type only allows AT or XA, got: \" + cfgValue);\n}","typeGuard":"boolean isValidDefault(BranchType t) { return t == BranchType.AT || t == BranchType.XA; }","tryCatchPattern":null,"preventionTips":["Restrict the config UI/enum for default-branch-type to at|xa","Rely on annotations for TCC/SAGA branch binding","Document that the default only covers AT/XA resource branches"],"tags":["config","branch-type","client","validation"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}