apache/seatunnel · error · PaimonConnectorException

BRANCH_NOT_EXISTS

BRANCH_NOT_EXISTS

Error message

${branchName}

What it means

PaimonSinkWriter.reOpenTableWrite re-resolves the Paimon table (e.g. after schema change) and re-validates the configured branch. If the branch configured in paimonSinkConfig no longer exists at reopen time, BRANCH_NOT_EXISTS is thrown with the bare branch name as the message.

Source

Thrown at seatunnel-connectors-v2/connector-paimon/src/main/java/org/apache/seatunnel/connectors/seatunnel/paimon/sink/PaimonSinkWriter.java:284

        this.sourceTableSchema =
                new AlterPaimonTableSchemaEventHandler(
                                sourceTableSchema,
                                paimonCatalog,
                                sinkPaimonTableSchema,
                                paimonTablePath,
                                paimonSinkConfig.getBranch())
                        .apply(event);
        reOpenTableWrite();
    }

    private void reOpenTableWrite() {
        this.seaTunnelRowType = this.sourceTableSchema.toPhysicalRowDataType();
        this.paimonTable = (FileStoreTable) paimonCatalog.getPaimonTable(paimonTablePath);
        String branchName = paimonSinkConfig.getBranch();
        if (StringUtils.isNotEmpty(branchName)) {
            BranchManager branchManager = paimonTable.branchManager();
            if (!branchManager.branchExists(branchName)) {
                throw new PaimonConnectorException(
                        PaimonConnectorErrorCode.BRANCH_NOT_EXISTS, branchName);
            }
            if (!branchManager.DEFAULT_MAIN_BRANCH.equalsIgnoreCase(branchName)) {
                this.paimonTable = this.paimonTable.switchToBranch(branchName);
                log.info("Re-switched to branch {} after reopening table", branchName);
            }
        }
        this.sinkPaimonTableSchema = this.paimonTable.schema();
        this.newTableWrite();
    }

    private void newTableWrite() {
        TableWrite oldTableWrite = this.tableWrite;
        tableWriteClose(oldTableWrite);
        this.tableWrite = this.paimonTable.newWrite(commitUser).withIOManager(ioManager);
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

1. Recreate the missing branch before restarting/resuming the job
2. Remove the `branch` option or point it to an existing branch
3. Prevent external jobs from deleting branches that active writers use

Example fix

null

BranchManager bm = paimonTable.branchManager(); if (!bm.branchExists(paimonSinkConfig.getBranch())) { bm.createBranch(paimonSinkConfig.getBranch()); }

try { writer.reOpenTableWrite(); } catch (PaimonConnectorException e) { if (PaimonConnectorErrorCode.BRANCH_NOT_EXISTS.equals(e.getErrorCode())) { /* recreate branch from config, then retry reopen */ } else { throw e; } }

When it happens

Trigger: applySchemaChange triggers reOpenTableWrite and `branchManager.branchExists(branchName)` returns false — the branch was dropped (e.g. by another job or cleanup) between job start and the reopen.

Common situations: Concurrent branch deletion by a maintenance/cleanup job; branch removed after a failed run; wrong warehouse path resolved after schema change reopen.

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

• BRANCH_NOT_EXISTS
• UNSUPPORTED_BRANCH_SAVE_MODE
• BRANCH_NOT_EXISTS
• Cross Partitions Upsert Dynamic Bucket Mode is not supported
• TABLE_WRITE_RECORD_FAILED

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