apache/iceberg · error · ViewAlreadyExistsException

View already exists: ${toIdentifier}

Error message

View already exists: ${toIdentifier}

What it means

renameView() maps a core AlreadyExistsException to Spark's ViewAlreadyExistsException naming the destination identifier. The rename target already holds a view (or another catalog object) with that name, and the catalog refuses to overwrite it.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java:760

  @Override
  public boolean dropView(Identifier ident) {
    if (null != asViewCatalog) {
      return asViewCatalog.dropView(buildIdentifier(ident));
    }

    return false;
  }

  @Override
  public void renameView(Identifier fromIdentifier, Identifier toIdentifier)
      throws NoSuchViewException, ViewAlreadyExistsException {
    if (null != asViewCatalog) {
      try {
        asViewCatalog.renameView(buildIdentifier(fromIdentifier), buildIdentifier(toIdentifier));
      } catch (org.apache.iceberg.exceptions.NoSuchViewException e) {
        throw new NoSuchViewException(fromIdentifier);
      } catch (org.apache.iceberg.exceptions.AlreadyExistsException e) {
        throw new ViewAlreadyExistsException(toIdentifier);
      }
    } else {
      throw new UnsupportedOperationException(
          "Renaming a view is not supported by catalog: " + catalogName);
    }
  }

  @Override
  public final void initialize(String name, CaseInsensitiveStringMap options) {
    super.initialize(name, options);

    boolean cacheEnabled =
        PropertyUtil.propertyAsBoolean(
            options, CatalogProperties.CACHE_ENABLED, CatalogProperties.CACHE_ENABLED_DEFAULT);

    boolean cacheCaseSensitive =
        PropertyUtil.propertyAsBoolean(
            options,

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Drop or rename the existing destination view first, then retry
  2. Choose a unique destination name for the rename
  3. Make the script idempotent: check existence of the target before renaming

Example fix

// before
spark.sql("ALTER VIEW analytics.v1 RENAME TO analytics.v2");
// after
spark.sql("DROP VIEW IF EXISTS analytics.v2");
spark.sql("ALTER VIEW analytics.v1 RENAME TO analytics.v2");
Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure destination name is free before renaming
boolean targetExists = ((org.apache.iceberg.catalog.ViewCatalog) catalog)
    .viewExists(org.apache.iceberg.catalog.TableIdentifier.of(toNs, toName));
if (targetExists) {
  throw new IllegalStateException("View already exists: " + toName);
}

Type guard

boolean isFree(org.apache.iceberg.catalog.ViewCatalog vc, Identifier ident) {
  return !vc.viewExists(org.apache.iceberg.catalog.TableIdentifier.of(ident.namespace().levels(), ident.name()));
}

Try / catch

try {
  catalog.renameView(from, to);
} catch (ViewAlreadyExistsException e) {
  logger.error("Destination view {} already exists; drop it or pick another name", to, e);
}

Prevention

When it happens

Trigger: Calling SparkCatalog.renameView(fromIdentifier, toIdentifier) when ViewCatalog.renameView throws org.apache.iceberg.exceptions.AlreadyExistsException because buildIdentifier(toIdentifier) already exists.

Common situations: Re-running a non-idempotent rename migration script; renaming to a name that already exists in the target namespace; concurrent jobs creating the destination view.

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

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