{"record":{"id":"effb00520b37bcd2","repo":"apache/iceberg","slug":"requirement-failed-branch-or-tag-s-is-missing-e","errorCode":null,"errorMessage":"Requirement failed: branch or tag %s is missing, expected %s","messagePattern":"Requirement failed: branch or tag (.+?) is missing, expected (.+?)","errorType":"exception","errorClass":"CommitFailedException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/UpdateRequirement.java","lineNumber":123,"sourceCode":"      return snapshotId;\n    }\n\n    @Override\n    public void validate(TableMetadata base) {\n      SnapshotRef ref = base.ref(name);\n      if (ref != null) {\n        String type = ref.isBranch() ? \"branch\" : \"tag\";\n        if (snapshotId == null) {\n          // a null snapshot ID means the ref should not exist already\n          throw new CommitFailedException(\n              \"Requirement failed: %s %s was created concurrently\", type, name);\n        } else if (snapshotId != ref.snapshotId()) {\n          throw new CommitFailedException(\n              \"Requirement failed: %s %s has changed: expected id %s != %s\",\n              type, name, snapshotId, ref.snapshotId());\n        }\n      } else if (snapshotId != null) {\n        throw new CommitFailedException(\n            \"Requirement failed: branch or tag %s is missing, expected %s\", name, snapshotId);\n      }\n    }\n  }\n\n  class AssertLastAssignedFieldId implements UpdateRequirement {\n    private final int lastAssignedFieldId;\n\n    public AssertLastAssignedFieldId(int lastAssignedFieldId) {\n      this.lastAssignedFieldId = lastAssignedFieldId;\n    }\n\n    public int lastAssignedFieldId() {\n      return lastAssignedFieldId;\n    }\n\n    @Override\n    public void validate(TableMetadata base) {","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/UpdateRequirement.java#L105-L141","documentation":"Thrown by AssertRefSnapshotId.validate when the requirement asserts that a branch or tag exists at a given snapshot ID, but the ref does not exist at all in the base metadata. This means the ref was deleted concurrently (or never existed) between when the operation was planned and when the commit validated. The commit fails with CommitFailedException and the operation must be re-planned against current state.","triggerScenarios":"Committing AssertRefSnapshotId(name, snapshotId) with a non-null snapshotId when base.ref(name) returns null — the branch/tag was removed by ExpireSnapshots/reference removal or was never created before this commit.","commonSituations":"Another job drops the branch/tag while a writer holds planned operations against it; a misconfigured environment points at a table where the ref name differs or was never created; REST catalog commits where the client cached an older table version that still contained the ref.","solutions":["Refresh table metadata and verify the ref exists before rebuilding and retrying the commit.","Recreate the missing branch/tag if its removal was unintended, then retry the update.","Re-plan the operation against the current table state rather than the cached snapshot reference.","Check for concurrent reference cleanup jobs (ExpireSnapshots, RemoveSnapshots, ref TTL automation) colliding with writers."],"exampleFix":"// before\ntable.manageSnapshots().fastForward(\"stage\").toSnapshot(id).commit(); // 'stage' deleted concurrently\n// after\ntable.refresh();\nif (table.ref(\"stage\") == null) {\n  table.manageSnapshots().createBranch(\"stage\").commit();\n}\ntable.manageSnapshots().fastForward(\"stage\").toSnapshot(id).commit();","handlingStrategy":"validation","validationCode":"table.refresh();\nPreconditions.checkArgument(table.ref(\"stage\") != null,\n    \"Ref %s does not exist in current metadata\", \"stage\");","typeGuard":null,"tryCatchPattern":"try {\n  commitRefOperation(\"stage\", id);\n} catch (CommitFailedException e) {\n  if (e.getMessage().contains(\"is missing\")) {\n    table.refresh();\n    recreateRefIfIntended();\n  } else { throw e; }\n}","preventionTips":["Verify the ref exists via table.refs() before operations that assert it","Check for concurrent cleanup jobs (ExpireSnapshots/ref removal) targeting the same refs","Confirm the ref name and catalog/database match — typos surface as 'missing'","Refresh metadata before commit instead of relying on cached state"],"tags":["concurrency","commit-failed","snapshot-ref","iceberg"],"backgroundTag":"resource-not-found","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}