{"record":{"id":"43efba6977bf6a31","repo":"apache/iceberg","slug":"unknown-transform-s-is-not-supported-43efba","errorCode":null,"errorMessage":"Unknown transform %s is not supported","messagePattern":"Unknown transform (.+?) is not supported","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/transforms/SortOrderVisitor.java","lineNumber":53,"sourceCode":"\n  T truncate(\n      String sourceName, int sourceId, int width, SortDirection direction, NullOrder nullOrder);\n\n  T year(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);\n\n  T month(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);\n\n  T day(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);\n\n  T hour(String sourceName, int sourceId, SortDirection direction, NullOrder nullOrder);\n\n  default T unknown(\n      String sourceName,\n      int sourceId,\n      String transform,\n      SortDirection direction,\n      NullOrder nullOrder) {\n    throw new UnsupportedOperationException(\n        String.format(\"Unknown transform %s is not supported\", transform));\n  }\n\n  /**\n   * Visit the fields of a {@link SortOrder}.\n   *\n   * @param sortOrder a sort order to visit\n   * @param visitor a sort order visitor\n   * @param <R> return type of the visitor\n   * @return a list of the result produced by visiting each sort field\n   */\n  @SuppressWarnings(\"checkstyle:CyclomaticComplexity\")\n  static <R> List<R> visit(SortOrder sortOrder, SortOrderVisitor<R> visitor) {\n    Schema schema = sortOrder.schema();\n    List<R> results = Lists.newArrayListWithExpectedSize(sortOrder.fields().size());\n\n    for (SortField field : sortOrder.fields()) {\n      String sourceName = schema.findColumnName(field.sourceId());","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/transforms/SortOrderVisitor.java#L35-L71","documentation":"SortOrderVisitor's default unknown() throws UnsupportedOperationException when a sort-order field uses a transform the visitor cannot interpret (an UnknownTransform, typically written by a newer Iceberg version or a custom transform). visit() dispatches unrecognized transforms to unknown(sourceName, sourceId, transform, direction, nullOrder); the throwing default means the concrete visitor has no policy for such fields.","triggerScenarios":"SortOrderVisitor.visit(order, visitor) on a SortOrder whose field transform resolves to UnknownTransform — e.g. sort order created by a newer Iceberg version or vendor custom transform — without an unknown(...) override in the visitor.","commonSituations":"Rolling upgrades where an older reader translates a table's sort order written by a newer release; third-party catalogs with custom sort transforms; metadata translation tools (e.g. to other table formats) missing the unknown hook.","solutions":["Override unknown(String sourceName, int sourceId, String transform, SortDirection direction, NullOrder nullOrder) to map or explicitly reject unrecognized transforms","Upgrade the Iceberg version so the transform binds to a known class","Inspect sortOrder with order.fields() before visiting to detect unknown transform strings and handle them up front"],"exampleFix":"// before\ndefault unknown() -> UnsupportedOperationException\n// after\n@Override\npublic String unknown(String sourceName, int sourceId, String transform,\n    SortDirection direction, NullOrder nullOrder) {\n  throw new IllegalArgumentException(\"Unsupported sort transform \" + transform + \"; upgrade Iceberg\");\n}","handlingStrategy":"validation","validationCode":"boolean hasUnknownSortTransform(SortOrder order) {\n  return order.fields().stream().anyMatch(f -> f.transform() instanceof UnknownTransform);\n}\n// check before SortOrderVisitor.visit(order, visitor)","typeGuard":"if (field.transform() instanceof UnknownTransform) {\n  throw new IllegalStateException(\"Unsupported sort transform: \" + field.transform());\n}","tryCatchPattern":"try {\n  SortOrderVisitor.visit(order, visitor);\n} catch (UnsupportedOperationException e) {\n  throw new IllegalStateException(\"Sort order uses unrecognized transform; upgrade Iceberg\", e);\n}","preventionTips":["Align reader/writer Iceberg versions to avoid UnknownTransform in sort orders","Override unknown(...) in SortOrderVisitor implementations to fail with the transform name","Pre-inspect order.fields() transform strings before metadata translation"],"tags":["java","sort-order","version-skew","visitor-pattern"],"backgroundTag":"unsupported-enum-value","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"}