apache/seatunnel · error · PaimonConnectorException

BRANCH_NOT_EXISTS

BRANCH_NOT_EXISTS

Error message

${branchName}

What it means

In the PaimonSink constructor, if the sink config specifies a non-empty `branch`, the connector checks `branchManager.branchExists(branchName)` on the target table and throws BRANCH_NOT_EXISTS with the bare branch name as the message when it is absent.

Source

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

        this.paimonBucketAssignerFactory = new PaimonBucketAssignerFactory();
        try (PaimonCatalog paimonCatalog = PaimonCatalog.loadPaimonCatalog(readonlyConfig)) {
            paimonCatalog.open();
            boolean databaseExists =
                    paimonCatalog.databaseExists(this.paimonSinkConfig.getNamespace());
            if (!databaseExists) {
                return;
            }
            TablePath tablePath = catalogTable.getTablePath();
            boolean tableExists = paimonCatalog.tableExists(tablePath);
            if (!tableExists) {
                return;
            }
            this.paimonTable = (FileStoreTable) paimonCatalog.getPaimonTable(tablePath);
            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 = paimonTable.switchToBranch(branchName);
                    log.info("Switch to branch {}", branchName);
                }
            }
        }
    }

    @Override
    public String getPluginName() {
        return PLUGIN_NAME;
    }

    @Override
    public PaimonSinkWriter createWriter(SinkWriter.Context context) throws IOException {
        return new PaimonSinkWriter(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Create the branch on the table before submitting the job (Paimon `create_branch` procedure)
2. Correct the `branch` option value in the sink config
3. Confirm the catalog/warehouse config resolves to the same table where the branch exists

Example fix

null

if (StringUtils.isNotEmpty(branchName)) { BranchManager bm = ((FileStoreTable) catalog.getPaimonTable(tablePath)).branchManager(); if (!bm.branchExists(branchName)) { bm.createBranch(branchName); } }

try { sink = new PaimonSink(...); } catch (PaimonConnectorException e) { if (PaimonConnectorErrorCode.BRANCH_NOT_EXISTS.equals(e.getErrorCode())) { /* branch = e.getMessage(); create it or correct config */ } else { throw e; } }

When it happens

Trigger: Instantiating PaimonSink with paimonSinkConfig.getBranch() set to a branch name that does not exist on the resolved tablePath in the Paimon catalog.

Common situations: Branch name typo; branch created after job submission but sink reads table from a different warehouse/catalog; branch deleted by retention cleanup; confusion between tag and branch names.

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/17667ff81966e8a6. Report an issue: GitHub.