{"record":{"id":"835caa4f6588877c","repo":"apache/iceberg","slug":"requirement-failed-uuid-does-not-match-expected","errorCode":null,"errorMessage":"Requirement failed: UUID does not match: expected %s != %s","messagePattern":"Requirement failed: UUID does not match: expected (.+?) != (.+?)","errorType":"exception","errorClass":"CommitFailedException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/UpdateRequirement.java","lineNumber":64,"sourceCode":"    }\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) {\n      if (!uuid.equalsIgnoreCase(base.uuid())) {\n        throw new CommitFailedException(\n            \"Requirement failed: UUID does not match: expected %s != %s\", base.uuid(), uuid);\n      }\n    }\n  }\n\n  class AssertViewUUID implements UpdateRequirement {\n    private final String uuid;\n\n    public AssertViewUUID(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","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/UpdateRequirement.java#L46-L82","documentation":"AssertTableUUID verifies that the base table metadata being committed has the UUID the client originally read. If base.uuid() does not case-insensitively match the requirement's expected uuid, validate throws CommitFailedException with both values. This prevents commits applied against a different (recreated) table than the one the client planned against.","triggerScenarios":"Committing table updates whose UpdateRequirement includes AssertTableUUID while the underlying table was dropped and recreated (new UUID), or the client read metadata from a different table instance/lineage.","commonSituations":"Drop-and-recreate of a table between a client's read and its commit; pointing a client at the wrong table location; catalog backends where metadata files from the old table linger.","solutions":["Refresh the table (catalog.loadTable / table.refresh()) and re-apply updates against current metadata, then retry the commit.","Verify the table was not dropped and recreated; if it was, redo the work against the new table UUID.","Catch CommitFailedException, reload base metadata, rebuild requirements with the new UUID, and retry."],"exampleFix":"// before\ncommitUpdate(reqs); // reqs contain stale AssertTableUUID(oldUuid)\n\n// after\ntry {\n  commitUpdate(reqs);\n} catch (CommitFailedException e) {\n  Table fresh = catalog.loadTable(ident); // re-read metadata, rebuild requirements with fresh.uuid()\n}","handlingStrategy":"retry","validationCode":"if (!expectedUuid.equalsIgnoreCase(currentTable.uuid())) { /* refresh and rebuild requirements before committing */ }","typeGuard":null,"tryCatchPattern":"try { commit(requirements); } catch (CommitFailedException e) { Table fresh = catalog.loadTable(ident); /* rebuild requirements with fresh.uuid() and retry */ }","preventionTips":["Refresh table metadata and re-check UUID before long-running commits.","Detect drop-and-recreate: a UUID mismatch means the table was recreated.","Retry commits by rebuilding requirements from freshly loaded metadata."],"tags":["commit-failed","uuid-mismatch","optimistic-concurrency"],"backgroundTag":"conflicting-concurrent-update","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"}