{"record":{"id":"0e717177c45cafdf","repo":"apache/iceberg","slug":"requirement-failed-default-sort-order-changed-ex","errorCode":null,"errorMessage":"Requirement failed: default sort order changed: expected id %s != %s","messagePattern":"Requirement failed: default sort order changed: expected id (.+?) != (.+?)","errorType":"exception","errorClass":"CommitFailedException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/UpdateRequirement.java","lineNumber":227,"sourceCode":"      }\n    }\n  }\n\n  class AssertDefaultSortOrderID implements UpdateRequirement {\n    private final int sortOrderId;\n\n    public AssertDefaultSortOrderID(int sortOrderId) {\n      this.sortOrderId = sortOrderId;\n    }\n\n    public int sortOrderId() {\n      return sortOrderId;\n    }\n\n    @Override\n    public void validate(TableMetadata base) {\n      if (sortOrderId != base.defaultSortOrderId()) {\n        throw new CommitFailedException(\n            \"Requirement failed: default sort order changed: expected id %s != %s\",\n            sortOrderId, base.defaultSortOrderId());\n      }\n    }\n  }\n}\n","sourceCodeStart":209,"sourceCodeEnd":234,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/UpdateRequirement.java#L209-L234","documentation":"Thrown by AssertDefaultSortOrderId.validate when the requirement's sortOrderId differs from base.defaultSortOrderId(). The requirement asserts that the table's default sort order is still the one planned against. A mismatch means a concurrent writer replaced the default sort order (sort-order evolution), so the commit is rejected.","triggerScenarios":"Committing updates with AssertDefaultSortOrderId when base.defaultSortOrderId() != sortOrderId — another writer ran UpdateSortOrder / replaced the default sort order concurrently between planning and commit validation.","commonSituations":"A sort-order optimization job racing with other metadata updates; two admin jobs both changing sort order; stale client metadata in REST catalog commits; automated table-maintenance pipelines colliding with ad-hoc admin changes.","solutions":["Refresh the table metadata, rebuild requirements from the current defaultSortOrderId, and retry.","Verify whether the operation is still valid under the new sort order and re-plan if writes depended on the old ordering.","Coordinate sort-order changes with a single maintenance job/owner to prevent concurrent switches.","Catch CommitFailedException and retry with backoff — the standard Iceberg optimistic-concurrency recovery."],"exampleFix":"// before\nUpdateRequirement req = new UpdateRequirement.AssertDefaultSortOrderId(1); // changed to 2\n// after\ntable.refresh();\nUpdateRequirement req = new UpdateRequirement.AssertDefaultSortOrderId(\n    table.sortOrder().orderId());","handlingStrategy":"retry","validationCode":"table.refresh();\nif (table.sortOrder().orderId() != expectedSortOrderId) {\n  throw new IllegalStateException(\"Default sort order changed; re-plan\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  commitWithRequirements(reqs);\n} catch (CommitFailedException e) {\n  if (e.getMessage().contains(\"default sort order changed\")) {\n    table.refresh();\n    reqs = rebuildRequirements(table);\n  } else { throw e; }\n}","preventionTips":["Refresh metadata before sort-order-dependent commits","Run sort-order changes in a single maintenance pipeline","Do not assume a fixed sort order across job runs; read it each time","Retry metadata commits with backoff on CommitFailedException"],"tags":["concurrency","sort-order","commit-failed","iceberg"],"backgroundTag":"invalid-state-transition","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}