{"record":{"id":"a194915837c646b5","repo":"apache/iceberg","slug":"sort-order-id-0-is-reserved-for-unsorted-order","errorCode":null,"errorMessage":"Sort order ID 0 is reserved for unsorted order","messagePattern":"Sort order ID 0 is reserved for unsorted order","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/SortOrder.java","lineNumber":278,"sourceCode":"      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();\n      } else {\n        throw new ValidationException(\n            \"Invalid term: %s, expected either a bound reference or transform\", term);\n      }\n    }\n  }","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/SortOrder.java#L260-L296","documentation":"Consistency check in SortOrder.Builder.buildUnchecked: the builder has sort fields but an explicit orderId of 0. Order ID 0 is reserved for the unsorted order in the Iceberg spec, so a populated sort order cannot carry it; the build is rejected before the SortOrder is created.","triggerScenarios":"Thrown at api/src/main/java/org/apache/iceberg/SortOrder.java:278 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Let the builder assign a fresh non-zero order ID by not calling orderId()","Supply a positive unique order ID obtained from the table metadata","Upgrade the sort order instead of rebuilding with ID 0"],"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"}