{"record":{"id":"04c73b3d47917c06","repo":"apache/iceberg","slug":"cannot-rename-s-as-s-for-backup-the-backup-tabl-04c73b","errorCode":null,"errorMessage":"Cannot rename %s as %s for backup. The backup table already exists.","messagePattern":"Cannot rename (.+?) as (.+?) for backup\\. The backup table already exists\\.","errorType":"exception","errorClass":"AlreadyExistsException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/actions/MigrateTableSparkAction.java","lineNumber":242,"sourceCode":"    Preconditions.checkArgument(\n        catalog instanceof SparkSessionCatalog,\n        \"Cannot migrate a table from a non-Iceberg Spark Session Catalog. Found %s of class %s as the source catalog.\",\n        catalog.name(),\n        catalog.getClass().getName());\n\n    return (TableCatalog) catalog;\n  }\n\n  private void renameAndBackupSourceTable() {\n    try {\n      LOG.info(\"Renaming {} as {} for backup\", sourceTableIdent(), backupIdent);\n      destCatalog().renameTable(sourceTableIdent(), backupIdent);\n\n    } catch (org.apache.spark.sql.catalyst.analysis.NoSuchTableException e) {\n      throw new NoSuchTableException(\"Cannot find source table %s\", sourceTableIdent());\n\n    } catch (org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException e) {\n      throw new AlreadyExistsException(\n          \"Cannot rename %s as %s for backup. The backup table already exists.\",\n          sourceTableIdent(), backupIdent);\n    }\n  }\n\n  private void restoreSourceTable() {\n    try {\n      LOG.info(\"Restoring {} from {}\", sourceTableIdent(), backupIdent);\n      destCatalog().renameTable(backupIdent, sourceTableIdent());\n\n    } catch (org.apache.spark.sql.catalyst.analysis.NoSuchTableException e) {\n      LOG.error(\n          \"Cannot restore the original table, the backup table {} cannot be found\", backupIdent, e);\n\n    } catch (org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException e) {\n      LOG.error(\n          \"Cannot restore the original table, a table with the original name exists. \"\n              + \"Use the backup table {} to restore the original table manually.\",","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/actions/MigrateTableSparkAction.java#L224-L260","documentation":"MigrateTableSparkAction fails when it tries to rename the source table to its backup identifier and the backup identifier already exists in the destination catalog (TableAlreadyExistsException), reported as AlreadyExistsException.","triggerScenarios":"doExecute -> renameAndBackupSourceTable: destCatalog().renameTable(sourceTableIdent, backupIdent) where a table already occupies the backup name (default: sourceIdent + \"_BACKUP__\").","commonSituations":"Re-running a migration after a previous attempt failed post-rename; manually created table with the _BACKUP__ suffix; stale backup table never cleaned up.","solutions":["Drop the existing backup table (after verifying it is disposable): DROP TABLE db.tbl_BACKUP__","Restore the previous backup as the source if the earlier run failed, then re-run migration","Use .backupTableName(\"unique_name\") to pick a fresh backup identifier"],"exampleFix":"// before\nSparkActions.get(spark).migrateTable(\"db.tbl\").execute(); // db.tbl_BACKUP__ exists\n// after\nSparkActions.get(spark).migrateTable(\"db.tbl\")\n    .backupTableName(\"db.tbl_backup_20260911\").execute();","handlingStrategy":"try-catch","validationCode":"if (spark.catalog().tableExists(backupIdentString)) { dropBackupOrChooseAlternateName(); }","typeGuard":null,"tryCatchPattern":"try { action.execute(); } catch (AlreadyExistsException e) { /* drop stale backup or set .backupTableName(newName) and retry */ }","preventionTips":["Always supply a unique .backupTableName() per run","Clean up backup tables after successful migrations","Check for _BACKUP__ collisions before running"],"tags":["spark","migrate-table","backup-table","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-23T08:17:48.524Z"}