{"record":{"id":"4576be2617a48475","repo":"apache/iceberg","slug":"tablealreadyexistsexception-to","errorCode":null,"errorMessage":"TableAlreadyExistsException(to)","messagePattern":"TableAlreadyExistsException\\(to\\)","errorType":"exception","errorClass":"TableAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":432,"sourceCode":"  private boolean catalogDropTable(Identifier ident) {\n    if (isPathIdentifier(ident)) {\n      return tables.dropTable(((PathIdentifier) ident).location(), false /* don't purge data */);\n    } else {\n      return icebergCatalog.dropTable(buildIdentifier(ident), false /* don't purge data */);\n    }\n  }\n\n  @Override\n  public void renameTable(Identifier from, Identifier to)\n      throws NoSuchTableException, TableAlreadyExistsException {\n    try {\n      checkNotPathIdentifier(from, \"renameTable\");\n      checkNotPathIdentifier(to, \"renameTable\");\n      icebergCatalog.renameTable(buildIdentifier(from), buildIdentifier(to));\n    } catch (org.apache.iceberg.exceptions.NoSuchTableException e) {\n      throw new NoSuchTableException(from);\n    } catch (AlreadyExistsException e) {\n      throw new TableAlreadyExistsException(to);\n    }\n  }\n\n  @Override\n  public void invalidateTable(Identifier ident) {\n    if (!isPathIdentifier(ident)) {\n      icebergCatalog.invalidateTable(buildIdentifier(ident));\n    }\n  }\n\n  @Override\n  public Identifier[] listTables(String[] namespace) {\n    return icebergCatalog.listTables(Namespace.of(namespace)).stream()\n        .map(ident -> Identifier.of(ident.namespace().levels(), ident.name()))\n        .toArray(Identifier[]::new);\n  }\n\n  @Override","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L414-L450","documentation":"Spark's renameTable failed because the target identifier already exists in the underlying Iceberg catalog; the Iceberg AlreadyExistsException was caught and rethrown as Spark's TableAlreadyExistsException. Iceberg catalogs refuse to overwrite an existing table during rename.","triggerScenarios":"ALTER TABLE from RENAME TO to where 'to' is an existing table; retried rename jobs where a previous attempt partially succeeded; creating a backup-name workflow that reuses an old target name without dropping it first.","commonSituations":"Idempotent pipelines that rerun renames; users expecting RENAME to overwrite like some engines do; schema-evolution scripts that cycle names (orders -> orders_old -> orders).","solutions":["Check target existence with spark.catalog().tableExists and drop or pick a different target name first.","If a retry is expected, drop the target table before re-running the rename.","Use unique, time-suffixed target names in automated pipelines.","If the stale target is unwanted, remove it via the same Iceberg catalog (not just the metastore)."],"exampleFix":"// before\nspark.sql(\"ALTER TABLE mydb.orders RENAME TO mydb.orders_v2\") // TableAlreadyExistsException\n\n// after\nif (spark.catalog().tableExists(\"iceberg_catalog.mydb.orders_v2\")) {\n  spark.sql(\"DROP TABLE iceberg_catalog.mydb.orders_v2\")\n}\nspark.sql(\"ALTER TABLE iceberg_catalog.mydb.orders RENAME TO iceberg_catalog.mydb.orders_v2\")","handlingStrategy":"validation","validationCode":"if (spark.catalog().tableExists(\"iceberg_catalog.mydb.orders_v2\")) {\n  spark.sql(\"DROP TABLE iceberg_catalog.mydb.orders_v2\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.renameTable(from, to);\n} catch (TableAlreadyExistsException e) {\n  // target exists: drop it or choose another name, then retry once\n}","preventionTips":["Check/drop target before rename","Use unique time-suffixed target names in pipelines","Make rename steps idempotent for retries","Do not reuse backup names across runs without cleanup"],"tags":["spark","catalog","rename","already-exists"],"backgroundTag":"file-already-exists","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}