apache/iceberg · error · TableAlreadyExistsException

TableAlreadyExistsException(ident)

Error message

TableAlreadyExistsException(ident)

What it means

checkViewNotExists throws TableAlreadyExistsException when creating or renaming a table whose target identifier is already occupied by a view. This guards the reverse collision of checkTableNotExists: a view exists where a table is being created. Iceberg treats views and tables as sharing one identifier space in the Spark session catalog.

Source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkSessionCatalog.java:664

    if (null != asViewCatalog && asViewCatalog.viewExists(fromIdentifier)) {
      asViewCatalog.renameView(fromIdentifier, toIdentifier);
    } else if (isViewCatalog()) {
      getSessionCatalog().renameView(fromIdentifier, toIdentifier);
    } else {
      throw new UnsupportedOperationException(
          "Renaming a view is not supported by catalog: " + catalogName);
    }
  }

  private void checkTableNotExists(Identifier ident) throws ViewAlreadyExistsException {
    if (tableExists(ident)) {
      throw new ViewAlreadyExistsException(ident);
    }
  }

  private void checkViewNotExists(Identifier ident) throws TableAlreadyExistsException {
    if (viewExists(ident)) {
      throw new TableAlreadyExistsException(ident);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Drop the view at that identifier before creating/renaming the table
2. Use a different table name
3. Check catalog.viewExists(ident) first and handle the collision explicitly
4. Ensure catalog names are unique across your table and view provisioning scripts

Example fix

// before
catalog.createTable(ident, schema); // TableAlreadyExistsException if ident is a view
// after
if (catalog.viewExists(ident)) {
  catalog.dropView(ident);
}
catalog.createTable(ident, schema);

if (catalog.viewExists(ident)) {
  throw new IllegalStateException("View " + ident + " blocks table creation at this name");
}

boolean nameFreeForTable = !catalog.viewExists(ident);

try {
  catalog.createTable(ident, schema, spec);
} catch (org.apache.iceberg.exceptions.TableAlreadyExistsException e) {
  // drop the view or pick another identifier
}

When it happens

Trigger: createTable/stageCreate targeting an identifier where a view exists; renameTable moving a table onto an existing view's name.

Common situations: Replacing a former view with a table without dropping it first; automated pipelines generating colliding names; restore/migration tooling that recreates tables where DDL drift left views.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• ViewAlreadyExistsException(ident)
• e (wrapped NoSuchNamespaceException)
• NoSuchViewException(ident)
• Creating a view is not supported by catalog: ${catalogName}
• Replacing a view is not supported by catalog: ${catalogName}

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/ba40b824c648eb86. Report an issue: GitHub.