{"record":{"id":"717029be997bcd23","repo":"apache/iceberg","slug":"tablealreadyexistsexception-ident","errorCode":null,"errorMessage":"TableAlreadyExistsException: <ident>","messagePattern":"TableAlreadyExistsException: <ident>","errorType":"exception","errorClass":"org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":219,"sourceCode":"    }\n  }\n\n  @Override\n  public Table createTable(\n      Identifier ident, StructType schema, Transform[] transforms, Map<String, String> properties)\n      throws TableAlreadyExistsException {\n    Schema icebergSchema = SparkSchemaUtil.convert(schema);\n    try {\n      Catalog.TableBuilder builder = newBuilder(ident, icebergSchema);\n      org.apache.iceberg.Table icebergTable =\n          builder\n              .withPartitionSpec(Spark3Util.toPartitionSpec(icebergSchema, transforms))\n              .withLocation(properties.get(\"location\"))\n              .withProperties(Spark3Util.rebuildCreateProperties(properties))\n              .create();\n      return new SparkTable(icebergTable);\n    } catch (AlreadyExistsException e) {\n      throw new TableAlreadyExistsException(ident);\n    }\n  }\n\n  @Override\n  public StagedTable stageCreate(\n      Identifier ident, StructType schema, Transform[] transforms, Map<String, String> properties)\n      throws TableAlreadyExistsException {\n    Schema icebergSchema = SparkSchemaUtil.convert(schema);\n    try {\n      Catalog.TableBuilder builder = newBuilder(ident, icebergSchema);\n      Transaction transaction =\n          builder\n              .withPartitionSpec(Spark3Util.toPartitionSpec(icebergSchema, transforms))\n              .withLocation(properties.get(\"location\"))\n              .withProperties(Spark3Util.rebuildCreateProperties(properties))\n              .createTransaction();\n      return new StagedSparkTable(transaction);\n    } catch (AlreadyExistsException e) {","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L201-L237","documentation":"When SparkCatalog.createTable calls the underlying Iceberg catalog's create(), the catalog may reject the creation because a table (or its metadata file) already exists at that identifier, surfacing AlreadyExistsException. Spark translates this into Spark's TableAlreadyExistsException carrying the identifier.","triggerScenarios":"Executing CREATE TABLE (without IF NOT EXISTS / OR REPLACE) on an identifier that already exists in the Iceberg catalog, or a stale metadata file at the target location causing an AlreadyExistsException during commit.","commonSituations":"Rerunning idempotent-looking DDL scripts without IF NOT EXISTS; concurrent jobs creating the same table; leftover metadata files from a failed/aborted create at the same location.","solutions":["Use CREATE TABLE IF NOT EXISTS if the table existing is acceptable.","Drop the existing table first (DROP TABLE) if it should be recreated.","Use CREATE OR REPLACE TABLE when intentional replacement is desired.","If caused by orphan metadata files, clean the stale metadata at the table location before retrying."],"exampleFix":"-- before\nCREATE TABLE catalog.db.t (id bigint) USING iceberg; -- throws if t exists\n-- after\nCREATE TABLE IF NOT EXISTS catalog.db.t (id bigint) USING iceberg;","handlingStrategy":"try-catch","validationCode":"-- Spark SQL precheck\nSHOW TABLES IN catalog.db LIKE 't';","typeGuard":null,"tryCatchPattern":"try {\n  spark.sql(\"CREATE TABLE catalog.db.t ... \");\n} catch (TableAlreadyExistsException e) {\n  // idempotent path: skip or replace\n  spark.sql(\"CREATE TABLE IF NOT EXISTS catalog.db.t ...\");\n}","preventionTips":["Use IF NOT EXISTS in DDL scripts intended to be re-runnable","Fully qualify catalog.namespace.table to avoid hitting an unintended catalog","Coordinate concurrent DDL for the same identifier across jobs","After failed creates, check for orphan metadata files at the target location"],"tags":["spark","ddl","table-already-exists","create-table"],"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"}