{"record":{"id":"9cf59c0e7f399b43","repo":"apache/iceberg","slug":"table-already-exists-s-9cf59c","errorCode":null,"errorMessage":"Table already exists: %s","messagePattern":"Table already exists: (.+?)","errorType":"exception","errorClass":"org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":267,"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, !cacheEnabled);\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":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L249-L285","documentation":"Spark's catalog API signals that a CREATE TABLE was issued for an identifier that already exists in the Iceberg catalog. SparkCatalog.createTable catches Iceberg's AlreadyExistsException from the underlying catalog's create() call and rethrows Spark's own org.apache.spark.sql.catalyst.analysis.TableAlreadyExistsException so Spark session/analysis layers handle it consistently.","triggerScenarios":"Calling CREATE TABLE (or DataFrameWriter.saveAsTable with mode ErrorIfExists/default) for an identifier that already exists; also CREATE TABLE without IF NOT EXISTS; the underlying icebergCatalog.create() throws AlreadyExistsException which is converted at line 267.","commonSituations":"Re-running a notebook or migration script that creates tables idempotently without IF NOT EXISTS; two jobs racing to create the same table; Spark session pointing at a catalog/namespace different from the one the developer assumed (table exists there); Hive vs Hadoop catalog confusion in multi-catalog setups.","solutions":["Use CREATE TABLE IF NOT EXISTS, or check catalog.tableExists(ident) before creating.","Wrap creation in try-catch on TableAlreadyExistsException and reuse the existing table.","Drop the stale table first (DROP TABLE) if it is safe to recreate.","Verify you are writing to the intended catalog/namespace (spark.sql.catalog.* configuration)."],"exampleFix":"// before\nspark.sql(\"CREATE TABLE db.events (id BIGINT) USING iceberg\")\n// after\nspark.sql(\"CREATE TABLE IF NOT EXISTS db.events (id BIGINT) USING iceberg\")","handlingStrategy":"try-catch","validationCode":"if (spark.catalog().tableExists(\"db\", \"events\")) { /* reuse or skip */ }","typeGuard":"boolean isFresh = spark instanceof SparkSession s && !s.catalog().tableExists(ident.namespace(), ident.name());","tryCatchPattern":"try { catalog.createTable(ident, schema, transforms, props); } catch (TableAlreadyExistsException e) { table = catalog.loadTable(ident); }","preventionTips":["Prefer IF NOT EXISTS in DDL scripts.","Make migration scripts idempotent.","Qualify identifiers with the intended catalog name.","Check tableExists before programmatic creation."],"tags":["spark","catalog","table-creation","idempotency"],"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"}