{"record":{"id":"f6712c9e6a571f6e","repo":"apache/iceberg","slug":"unsorted-order-id-must-be-0","errorCode":null,"errorMessage":"Unsorted order ID must be 0","messagePattern":"Unsorted order ID must be 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/SortOrder.java","lineNumber":272,"sourceCode":"    }\n\n    Builder addSortField(\n        Transform<?, ?> transform, int sourceId, SortDirection direction, NullOrder nullOrder) {\n      SortField sortField = new SortField(transform, sourceId, direction, nullOrder);\n      fields.add(sortField);\n      return this;\n    }\n\n    public SortOrder build() {\n      SortOrder sortOrder = buildUnchecked();\n      checkCompatibility(sortOrder, schema);\n      return sortOrder;\n    }\n\n    SortOrder buildUnchecked() {\n      if (fields.isEmpty()) {\n        if (orderId != null && orderId != 0) {\n          throw new IllegalArgumentException(\"Unsorted order ID must be 0\");\n        }\n        return SortOrder.unsorted();\n      }\n\n      if (orderId != null && orderId == 0) {\n        throw new IllegalArgumentException(\"Sort order ID 0 is reserved for unsorted order\");\n      }\n\n      // default ID to 1 as 0 is reserved for unsorted order\n      int actualOrderId = orderId != null ? orderId : 1;\n      return new SortOrder(schema, actualOrderId, fields);\n    }\n\n    private Transform<?, ?> toTransform(BoundTerm<?> term) {\n      if (term instanceof BoundReference) {\n        return Transforms.identity(term.type());\n      } else if (term instanceof BoundTransform) {\n        return ((BoundTransform<?, ?>) term).transform();","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/SortOrder.java#L254-L290","documentation":"Consistency check in SortOrder.Builder.buildUnchecked: the builder has no sort fields (which by definition produces the unsorted order) but was explicitly given a non-zero orderId. Iceberg reserves order ID 0 for the unsorted order, so an empty field list with any other ID is contradictory and rejected.","triggerScenarios":"Thrown at api/src/main/java/org/apache/iceberg/SortOrder.java:272 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Omit the order ID so the builder defaults correctly for unsorted orders","Pass orderId 0 when building an empty (unsorted) sort order","Add at least one sort field if a non-zero order ID is intended"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}