{"record":{"id":"8a52d79002107417","repo":"apache/iceberg","slug":"requirement-failed-table-already-exists","errorCode":null,"errorMessage":"Requirement failed: table already exists","messagePattern":"Requirement failed: table already exists","errorType":"exception","errorClass":"CommitFailedException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/UpdateRequirement.java","lineNumber":44,"sourceCode":"/** Represents a requirement for a {@link MetadataUpdate} */\npublic interface UpdateRequirement {\n  default void validate(TableMetadata base) {\n    throw new ValidationException(\n        \"Cannot validate %s against a table\", this.getClass().getSimpleName());\n  }\n\n  default void validate(ViewMetadata base) {\n    throw new ValidationException(\n        \"Cannot validate %s against a view\", this.getClass().getSimpleName());\n  }\n\n  class AssertTableDoesNotExist implements UpdateRequirement {\n    public AssertTableDoesNotExist() {}\n\n    @Override\n    public void validate(TableMetadata base) {\n      if (base != null) {\n        throw new CommitFailedException(\"Requirement failed: table already exists\");\n      }\n    }\n  }\n\n  class AssertTableUUID implements UpdateRequirement {\n    private final String uuid;\n\n    public AssertTableUUID(String uuid) {\n      Preconditions.checkArgument(uuid != null, \"Invalid required UUID: null\");\n      this.uuid = uuid;\n    }\n\n    public String uuid() {\n      return uuid;\n    }\n\n    @Override\n    public void validate(TableMetadata base) {","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/UpdateRequirement.java#L26-L62","documentation":"AssertTableDoesNotExist is a commit requirement for table creation. During a commit, if a non-null base TableMetadata is returned (meaning the table already exists in the catalog), validate throws CommitFailedException so the create-table operation fails cleanly instead of overwriting.","triggerScenarios":"Issuing a create-table commit (with AssertTableDoesNotExist requirement) to a catalog where a table with that identifier already exists.","commonSituations":"Concurrent create attempts of the same table; retrying a create that previously succeeded; not checking catalog existence before create; metastores with eventual consistency returning stale null.","solutions":["Catch CommitFailedException and treat it as 'table already exists'; proceed to load the existing table or fail gracefully.","Check catalog.tableExists(identifier) before issuing the create commit.","Use create-or-replace semantics (catalog.createTransaction/buildReplace) if overwrite is intended.","Resolve concurrent creators via a single coordinator or unique table names."],"exampleFix":"// before\ntable = catalog.buildTable(ident, schema).create(); // CommitFailedException if exists\n\n// after\ntry {\n  table = catalog.buildTable(ident, schema).create();\n} catch (CommitFailedException e) {\n  table = catalog.loadTable(ident); // already created concurrently\n}","handlingStrategy":"try-catch","validationCode":"if (catalog.tableExists(identifier)) { /* load existing or use replace semantics */ }","typeGuard":null,"tryCatchPattern":"try { catalog.buildTable(ident, schema).create(); } catch (CommitFailedException e) { /* table already exists: load or abort */ }","preventionTips":["Check tableExists before create; use create-or-replace when overwrite is intended.","Expect concurrent creators; treat CommitFailedException on create as 'exists'.","Avoid retry loops that blindly re-issue create after a failure."],"tags":["commit-failed","table-already-exists","concurrency"],"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-14T21:17:11.552Z"}