{"record":{"id":"bf3bf003359f106b","repo":"apache/seatunnel","slug":"branch-not-exists","errorCode":"BRANCH_NOT_EXISTS","errorMessage":"Specified branch '%s' of table '%s' does not exist.","messagePattern":"Specified branch '(.+?)' of table '(.+?)' does not exist\\.","errorType":"error_code","errorClass":"PaimonConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/handler/PaimonSaveModeHandler.java","lineNumber":101,"sourceCode":"        super.handleSchemaSaveModeWithRestore();\n    }\n\n    private boolean isNonMainBranch() {\n        return StringUtils.isNotEmpty(branch)\n                && !BranchManager.DEFAULT_MAIN_BRANCH.equalsIgnoreCase(branch);\n    }\n\n    private void checkBranchSaveMode() {\n        if (!isNonMainBranch()) {\n            return;\n        }\n        if (!catalog.tableExists(tablePath)) {\n            throw unsupportedBranchSaveMode(\n                    \"The main table must exist before writing to a non-main branch.\");\n        }\n        Table paimonTable = ((PaimonCatalog) catalog).getPaimonTable(tablePath);\n        if (!((FileStoreTable) paimonTable).branchManager().branchExists(branch)) {\n            throw new PaimonConnectorException(\n                    PaimonConnectorErrorCode.BRANCH_NOT_EXISTS,\n                    String.format(\n                            \"Specified branch '%s' of table '%s' does not exist.\",\n                            branch, tablePath));\n        }\n        if (this.schemaSaveMode == SchemaSaveMode.RECREATE_SCHEMA) {\n            throw unsupportedBranchSaveMode(\n                    \"schema_save_mode=RECREATE_SCHEMA would drop and recreate the main table.\");\n        }\n        if (this.dataSaveMode == DataSaveMode.DROP_DATA) {\n            throw unsupportedBranchSaveMode(\n                    \"data_save_mode=DROP_DATA would truncate the main table.\");\n        }\n    }\n\n    private PaimonConnectorException unsupportedBranchSaveMode(String reason) {\n        return new PaimonConnectorException(\n                PaimonConnectorErrorCode.UNSUPPORTED_BRANCH_SAVE_MODE,","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/handler/PaimonSaveModeHandler.java#L83-L119","documentation":"PaimonSaveModeHandler.checkBranchSaveMode verifies that a target branch exists before applying save-mode actions. If the configured branch does not exist on the Paimon table, BRANCH_NOT_EXISTS is thrown. Note the main table itself must also exist before writing to a non-main branch.","triggerScenarios":"Calling handleSchemaSaveMode, handleDataSaveMode, or handleSchemaSaveModeWithRestore with a sink `branch` option naming a branch that `branchManager.branchExists()` reports as absent (or the main table missing entirely).","commonSituations":"Typo in the branch name in HOCON config; branch was created in a different catalog/warehouse path; branch dropped by another job; user assumes `CREATE_SCHEMA_WHEN_NOT_EXIST` auto-creates branches (it does not).","solutions":["Create the branch first, e.g. via Paimon Flink/Spark SQL `CALL sys.create_branch(...)` or `ALTER TABLE ... CREATE BRANCH`","Fix the `branch` value in the SeaTunnel sink config to match an existing branch","Verify the catalog warehouse path points to the table that actually contains the branch"],"exampleFix":"// before\nbranch = \"feature-1\" // branch never created\n// after: create it first\n// ALTER TABLE my_table CREATE BRANCH feature-1;\nbranch = \"feature-1\"\n","handlingStrategy":"validation","validationCode":"Catalog catalog = ...; TablePath tp = TablePath.of(db, table); if (!catalog.tableExists(tp)) throw ...; PaimonTable t = ((PaimonCatalog) catalog).getPaimonTable(tp); if (!t.branchManager().branchExists(branchName)) { /* create branch or fix config */ }","typeGuard":null,"tryCatchPattern":"try { handler.handleSchemaSaveMode(); } catch (PaimonConnectorException e) { if (PaimonConnectorErrorCode.BRANCH_NOT_EXISTS.equals(e.getErrorCode())) { /* create branch, then retry once */ } else { throw e; } }","preventionTips":["List existing branches (`SHOW BRANCHES` / branchManager.branches()) before configuring `branch`","Never assume save modes auto-create branches","Pin catalog warehouse config consistently across jobs"],"tags":["paimon","branch","config"],"backgroundTag":"resource-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}