{"record":{"id":"888f260a6595ad18","repo":"apache/iceberg","slug":"string-format-invalid-term-s-expected-either-a","errorCode":null,"errorMessage":"String.format(\"Invalid term: %s, expected either a bound reference or transform\", term)","messagePattern":"String\\.format\\(\"Invalid term: (.+?), expected either a bound reference or transform\", term\\)","errorType":"validation","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/SortOrder.java","lineNumber":292,"sourceCode":"        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  }\n\n  public static void checkCompatibility(SortOrder sortOrder, Schema schema) {\n    for (SortField field : sortOrder.fields) {\n      Type sourceType = schema.findType(field.sourceId());\n      ValidationException.check(\n          sourceType != null, \"Cannot find source column for sort field: %s\", field);\n      ValidationException.check(\n          sourceType.isPrimitiveType(),\n          \"Cannot sort by non-primitive source field: %s\",\n          sourceType);\n      ValidationException.check(\n          field.transform().canTransform(sourceType),\n          \"Invalid source type %s for transform: %s\",\n          sourceType,","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/SortOrder.java#L274-L310","documentation":"Type check in SortOrder.Builder.toTransform: the term passed to sortField is neither a BoundReference (a plain column) nor a BoundTransform (a transform applied to a column), so it cannot be converted into a sort field. The %s is the offending term; common causes are passing an UnboundTerm or an arbitrary Term subtype that was never bound to a schema.","triggerScenarios":"Thrown at api/src/main/java/org/apache/iceberg/SortOrder.java:292 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Bind the term against the table schema before adding it as a sort field","Use Expressions.col(...).plus metadata binding via the table's resolver to obtain a BoundReference/BoundTransform","Reject unsupported term types at the API boundary with a clearer message"],"exampleFix":null,"handlingStrategy":"type-guard","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"}