{"record":{"id":"86efe2a498e19b7e","repo":"apache/iceberg","slug":"org-apache-iceberg-exceptions-alreadyexistsexcepti","errorCode":null,"errorMessage":"org.apache.iceberg.exceptions.AlreadyExistsException: ","messagePattern":"org\\.apache\\.iceberg\\.exceptions\\.AlreadyExistsException: ","errorType":"exception","errorClass":"TableAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java","lineNumber":268,"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":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/SparkCatalog.java#L250-L286","documentation":"SparkCatalog.createTable maps Iceberg's AlreadyExistsException (raised by the underlying catalog's TableBuilder.create() because an identifier or location already exists) to Spark's TableAlreadyExistsException. Spark raises it to the user as a TABLE_OR_VIEW_ALREADY_EXISTS-style failure.","triggerScenarios":"CREATE TABLE catalog.db.name ... when the table already exists in the catalog, or when another table is already registered at the requested custom location.","commonSituations":"Re-running idempotent-looking DDL scripts; races between concurrent Spark jobs creating the same table; stale catalog metadata in V2 session catalogs.","solutions":["Use CREATE TABLE IF NOT EXISTS or stageCreateOrReplace semantics if replacement is intended.","Check tableExists(ident) before creating in code that must be idempotent.","If a different table legitimately occupies the location, choose a new location or drop the conflicting table first.","Handle TableAlreadyExistsException in the caller when racing concurrent creates."],"exampleFix":"// before\nspark.sql(\"CREATE TABLE prod.db.events (id BIGINT) USING iceberg\");\n// after\nspark.sql(\"CREATE TABLE IF NOT EXISTS prod.db.events (id BIGINT) USING iceberg\");","handlingStrategy":"try-catch","validationCode":"if (catalog.tableExists(ident)) {\n  throw new IllegalArgumentException(\"Table already exists: \" + ident);\n}","typeGuard":null,"tryCatchPattern":"try {\n  spark.sql(createTableSql);\n} catch (TableAlreadyExistsException e) {\n  LOG.warn(\"Table {} already exists, skipping create\", ident);\n  return spark.table(ident.toString());\n}","preventionTips":["Use CREATE TABLE IF NOT EXISTS for idempotent DDL.","Pre-check tableExists before programmatic createTable.","Serialize concurrent create jobs or use unique names.","Remember the custom 'location' can also collide with another table."],"tags":["spark","iceberg","ddl","table-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"}