apache/iceberg · error · CommitFailedException

Requirement failed: view UUID does not match: expected

Error message

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

What it means

AssertViewUUID is the view counterpart of AssertTableUUID: it asserts the base view metadata still has the UUID the client read. On mismatch, validate throws CommitFailedException with expected and actual UUIDs, protecting view commits from being applied to a recreated view.

Solutions

Reload the view (catalog.loadView / refresh) to obtain current metadata and retry with rebuilt requirements.
Detect the drop-and-recreate scenario and reapply changes against the new view UUID.
Catch CommitFailedException, refresh, and re-run the update transaction.

Example fix

// before
view.updateSchema(...).commit(); // fails after view recreate

// after
try {
  view.updateSchema(...).commit();
} catch (CommitFailedException e) {
  View fresh = catalog.loadView(ident); // rebuild update against fresh.uuid()
}

Defensive patterns

Strategy: retry

Validate before calling

if (!expectedUuid.equalsIgnoreCase(currentView.uuid())) { /* reload view and rebuild requirements */ }

Try / catch

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

Prevention

Reload view metadata before committing after long edit sessions.
Treat UUID mismatch as evidence the view was dropped and recreated.
Keep view update clients short-lived to reduce stale-UUID windows.

When it happens

Trigger: Committing view definition updates with an AssertViewUUID requirement while the view was dropped and recreated between the client's read and the commit.

Common situations: Concurrent drop/recreate of a view; stale long-lived clients holding an old ViewVersion; environments where views are recreated by deployment scripts.

Related errors

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

Appendix: source

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

    }
  }

  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
    public void validate(ViewMetadata base) {
      if (!uuid.equalsIgnoreCase(base.uuid())) {
        throw new CommitFailedException(
            "Requirement failed: view UUID does not match: expected %s != %s", base.uuid(), uuid);
      }
    }
  }

  class AssertRefSnapshotID implements UpdateRequirement {
    private final String name;
    private final Long snapshotId;

    public AssertRefSnapshotID(String name, Long snapshotId) {
      this.name = name;
      this.snapshotId = snapshotId;
    }

    public String refName() {
      return name;
    }

View on GitHub (pinned to 86d9c8fc54)