apache/iceberg · error · CommitFailedException

Requirement failed: UUID does not match: expected

Error message

Requirement failed: UUID does not match: expected %s != %s

What it means

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.

Solutions

1. Refresh the table (catalog.loadTable / table.refresh()) and re-apply updates against current metadata, then retry the commit.
2. Verify the table was not dropped and recreated; if it was, redo the work against the new table UUID.
3. Catch CommitFailedException, reload base metadata, rebuild requirements with the new UUID, and retry.

Example fix

// before
commitUpdate(reqs); // reqs contain stale AssertTableUUID(oldUuid)

// after
try {
  commitUpdate(reqs);
} catch (CommitFailedException e) {
  Table fresh = catalog.loadTable(ident); // re-read metadata, rebuild requirements with fresh.uuid()
}

if (!expectedUuid.equalsIgnoreCase(currentTable.uuid())) { /* refresh and rebuild requirements before committing */ }

try { commit(requirements); } catch (CommitFailedException e) { Table fresh = catalog.loadTable(ident); /* rebuild requirements with fresh.uuid() and retry */ }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Requirement failed: view UUID does not match: expected
• Cannot commit: Base metadata location
• Cannot commit : metadata location has changed from
• Cannot commit : metadata location has changed from
• Cannot commit: stale table metadata

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/835caa4f6588877c. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/UpdateRequirement.java:64

    }
  }

  class AssertTableUUID implements UpdateRequirement {
    private final String uuid;

    public AssertTableUUID(String uuid) {
      Preconditions.checkArgument(uuid != null, "Invalid required UUID: null");
      this.uuid = uuid;
    }

    public String uuid() {
      return uuid;
    }

    @Override
    public void validate(TableMetadata base) {
      if (!uuid.equalsIgnoreCase(base.uuid())) {
        throw new CommitFailedException(
            "Requirement failed: UUID does not match: expected %s != %s", base.uuid(), uuid);
      }
    }
  }

  class AssertViewUUID implements UpdateRequirement {
    private final String uuid;

    public AssertViewUUID(String uuid) {
      Preconditions.checkArgument(uuid != null, "Invalid required UUID: null");
      this.uuid = uuid;
    }

    public String uuid() {
      return uuid;
    }

    @Override

View on GitHub (pinned to 86d9c8fc54)