{"record":{"id":"fd53637d5959abda","repo":"apache/iceberg","slug":"cannot-convert-unknown-expression-expr-fd5363","errorCode":null,"errorMessage":"Cannot convert unknown expression: <expr>","messagePattern":"Cannot convert unknown expression: <expr>","errorType":"exception","errorClass":"java.lang.UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java","lineNumber":421,"sourceCode":"                  .map(ref -> DOT.join(ref.fieldNames()))\n                  .map(org.apache.iceberg.expressions.Expressions::ref)\n                  .collect(Collectors.toList()));\n        case \"hilbert\":\n          return new Hilbert(\n              Stream.of(transform.references())\n                  .map(ref -> DOT.join(ref.fieldNames()))\n                  .map(org.apache.iceberg.expressions.Expressions::ref)\n                  .collect(Collectors.toList()));\n        default:\n          throw new UnsupportedOperationException(\"Transform is not supported: \" + transform);\n      }\n\n    } else if (expr instanceof NamedReference) {\n      NamedReference ref = (NamedReference) expr;\n      return org.apache.iceberg.expressions.Expressions.ref(DOT.join(ref.fieldNames()));\n\n    } else {\n      throw new UnsupportedOperationException(\"Cannot convert unknown expression: \" + expr);\n    }\n  }\n\n  /**\n   * Converts Spark transforms into a {@link PartitionSpec}.\n   *\n   * @param schema the table schema\n   * @param partitioning Spark Transforms\n   * @return a PartitionSpec\n   */\n  public static PartitionSpec toPartitionSpec(Schema schema, Transform[] partitioning) {\n    if (partitioning == null || partitioning.length == 0) {\n      return PartitionSpec.unpartitioned();\n    }\n\n    PartitionSpec.Builder builder = PartitionSpec.builderFor(schema);\n    for (Transform transform : partitioning) {\n      Preconditions.checkArgument(","sourceCodeStart":403,"sourceCodeEnd":439,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java#L403-L439","documentation":"toIcebergTerm handles two kinds of Spark expression trees: transforms and NamedReference (plain column references). Anything else at the top level cannot be mapped to an Iceberg Term and throws UnsupportedOperationException with the expression's toString.","triggerScenarios":"Passing a complex Spark expression (e.g. a predicate or function call, not a bare column or transform) into Spark3Util.toIcebergTerm.","commonSituations":"DDL constructs like ORDER/CLUSTER BY with computed expressions rather than plain columns; custom extensions emitting arbitrary expressions where only references/transforms are expected.","solutions":["Use plain column references or supported transforms in the DDL clause","Pre-compute complex expressions into a materialized column, then reference that column","Validate the expression is a Transform or NamedReference before calling toIcebergTerm"],"exampleFix":"// before\nSORTED BY (upper(name));\n// after\nSORTED BY (name);","handlingStrategy":"type-guard","validationCode":"if (!(expr instanceof Transform) && !(expr instanceof NamedReference)) {\n  throw new IllegalArgumentException(\"Only columns and transforms are supported: \" + expr);\n}","typeGuard":"static boolean isConvertibleTerm(Expression expr) {\n  return expr instanceof Transform || expr instanceof NamedReference;\n}","tryCatchPattern":"try {\n  Term term = Spark3Util.toIcebergTerm(expr);\n} catch (UnsupportedOperationException e) {\n  // surface a clear DDL error telling users to use plain columns or transforms\n}","preventionTips":["Only accept bare columns or supported transforms in DDL clauses that map to Iceberg terms","Pre-compute complex expressions into columns","Reject arbitrary expressions in DDL validation"],"tags":["spark","expression","unsupported-operation"],"backgroundTag":"unsupported-operation","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"}