apache/seatunnel · error · PaimonConnectorException

BRANCH_NOT_EXISTS

BRANCH_NOT_EXISTS

Error message

Specified branch '%s' of table '%s' does not exist.

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/handler/PaimonSaveModeHandler.java:101

        super.handleSchemaSaveModeWithRestore();
    }

    private boolean isNonMainBranch() {
        return StringUtils.isNotEmpty(branch)
                && !BranchManager.DEFAULT_MAIN_BRANCH.equalsIgnoreCase(branch);
    }

    private void checkBranchSaveMode() {
        if (!isNonMainBranch()) {
            return;
        }
        if (!catalog.tableExists(tablePath)) {
            throw unsupportedBranchSaveMode(
                    "The main table must exist before writing to a non-main branch.");
        }
        Table paimonTable = ((PaimonCatalog) catalog).getPaimonTable(tablePath);
        if (!((FileStoreTable) paimonTable).branchManager().branchExists(branch)) {
            throw new PaimonConnectorException(
                    PaimonConnectorErrorCode.BRANCH_NOT_EXISTS,
                    String.format(
                            "Specified branch '%s' of table '%s' does not exist.",
                            branch, tablePath));
        }
        if (this.schemaSaveMode == SchemaSaveMode.RECREATE_SCHEMA) {
            throw unsupportedBranchSaveMode(
                    "schema_save_mode=RECREATE_SCHEMA would drop and recreate the main table.");
        }
        if (this.dataSaveMode == DataSaveMode.DROP_DATA) {
            throw unsupportedBranchSaveMode(
                    "data_save_mode=DROP_DATA would truncate the main table.");
        }
    }

    private PaimonConnectorException unsupportedBranchSaveMode(String reason) {
        return new PaimonConnectorException(
                PaimonConnectorErrorCode.UNSUPPORTED_BRANCH_SAVE_MODE,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Create the branch first, e.g. via Paimon Flink/Spark SQL `CALL sys.create_branch(...)` or `ALTER TABLE ... CREATE BRANCH`
2. Fix the `branch` value in the SeaTunnel sink config to match an existing branch
3. Verify the catalog warehouse path points to the table that actually contains the branch

Example fix

// before
branch = "feature-1" // branch never created
// after: create it first
// ALTER TABLE my_table CREATE BRANCH feature-1;
branch = "feature-1"

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 */ }

try { handler.handleSchemaSaveMode(); } catch (PaimonConnectorException e) { if (PaimonConnectorErrorCode.BRANCH_NOT_EXISTS.equals(e.getErrorCode())) { /* create branch, then retry once */ } else { throw e; } }

When it happens

Trigger: 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).

Common situations: 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).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• NON_PRIMARY_KEY_CHECK_ERROR
• BRANCH_NOT_EXISTS
• BRANCH_NOT_EXISTS
• ${e.message}
• CONFIG_VALIDATION_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/bf3bf003359f106b. Report an issue: GitHub.