What causes "Branch %s doesn't exist in table %s" in prestodb/presto?

Verify the branch exists via table refs (e.g. inspect the table's branches in Iceberg metadata) before dropping.

prestodb/presto · error · PrestoException

NOT_FOUND

NOT_FOUND

Error message

Branch %s doesn't exist in table %s

What it means

Thrown when dropping a branch that does not exist on the Iceberg table. The connector checks table.refs() for a branch with the given name and, if absent (and the caller did not opt into if-exists semantics), fails with NOT_FOUND.

Source

Thrown at presto-iceberg/src/main/java/com/facebook/presto/iceberg/IcebergAbstractMetadata.java:1148

    }

    public void rollback()
    {
        transactionContext.rollback();
    }

    @Override
    public void dropBranch(ConnectorSession session, ConnectorTableHandle tableHandle, String branchName, boolean branchExists)
    {
        IcebergTableHandle icebergTableHandle = (IcebergTableHandle) tableHandle;
        verify(icebergTableHandle.getIcebergTableName().getTableType() == DATA, "only the data table can have branch dropped");
        Table icebergTable = getIcebergTable(session, icebergTableHandle.getSchemaTableName());
        if (icebergTable.refs().containsKey(branchName) && icebergTable.refs().get(branchName).isBranch()) {
            icebergTable.manageSnapshots().removeBranch(branchName).commit();
        }
        else {
            if (!branchExists) {
                throw new PrestoException(NOT_FOUND, format("Branch %s doesn't exist in table %s", branchName, icebergTableHandle.getSchemaTableName().getTableName()));
            }
        }
    }

    @Override
    public void createBranch(
            ConnectorSession session,
            ConnectorTableHandle tableHandle,
            String branchName,
            boolean replace,
            boolean ifNotExists,
            Optional<ConnectorTableVersion> tableVersion,
            Optional<Long> retainDays,
            Optional<Integer> minSnapshotsToKeep,
            Optional<Long> maxSnapshotAgeDays)
    {
        IcebergTableHandle icebergTableHandle = (IcebergTableHandle) tableHandle;
        verify(icebergTableHandle.getIcebergTableName().getTableType() == DATA, "only the data table can have branch created");

View on GitHub (pinned to 55bb57d202)

Solutions

Verify the branch exists via table refs (e.g. inspect the table's branches in Iceberg metadata) before dropping.
Use IF EXISTS so a missing branch is a no-op instead of an error.
Correct the branch name (check case sensitivity).

Example fix

// before
ALTER TABLE t DROP BRANCH audit_2024; -- branch doesn't exist
// after
ALTER TABLE t DROP BRANCH IF EXISTS audit_2024;

Defensive patterns

Strategy: validation

Validate before calling

-- check branch existence before dropping
SELECT * FROM "t$refs" WHERE name = 'audit_2024' AND type = 'BRANCH';

Try / catch

try { dropBranch(...); }
catch (PrestoException e) { if (NOT_FOUND.equals(e.getErrorCode())) { /* treat as no-op or fix the name */ } }

Prevention

Always use DROP BRANCH IF EXISTS in scripts
List refs before dropping
Watch for retention jobs that may remove branches first

When it happens

Trigger: Executing ALTER TABLE ... DROP BRANCH <name> where the branch name is misspelled or the branch was already removed; also raised when a caller passes branchExists=false and the branch is missing.

Common situations: Typo in branch name; branch already deleted by another job/user; running the drop twice; branch only exists in another catalog or table.

Understand the failure class

Background: NOT_FOUND error code: why tRPC, Harbor, Nacos and other libraries return 404 "not found" errors for resources that may still exist — this error's family across 11 libraries.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/4079f49a0948a80b. Report an issue: GitHub.