{"record":{"id":"856cf49025635d57","repo":"apache/iceberg","slug":"cannot-convert-unknown-expression-expr-856cf4","errorCode":null,"errorMessage":"Cannot convert unknown expression: ${expr}","messagePattern":"Cannot convert unknown expression: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java","lineNumber":438,"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":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java#L420-L456","documentation":"Thrown by Spark3Util.toIcebergTerm when the input expression is neither a Transform nor a NamedReference. Iceberg terms can only be derived from column references or transforms, so any other Spark Expression subclass cannot be converted.","triggerScenarios":"Passing computed/literal expressions (e.g. Literal, arithmetic expressions) into toIcebergTerm instead of a plain column reference or transform.","commonSituations":"Custom catalog code extracting terms from arbitrary Spark expressions; DDL features that embed expressions where Iceberg expects a bare column name.","solutions":["Ensure the expression is a plain column reference (NamedReference) or Transform","Extract and pass the underlying column names instead of the computed expression","Simplify the DDL so terms reference columns directly"],"exampleFix":"// before\nExpressions.ref(exprToString(Literal.of(1)));\n// after\nExpressions.ref(\"column_name\");","handlingStrategy":"type-guard","validationCode":"if (!(expr instanceof Transform) && !(expr instanceof NamedReference)) {\n  throw new IllegalArgumentException(\"Expression must be a Transform or NamedReference\");\n}","typeGuard":"boolean isConvertibleTerm(Expression expr) {\n  return expr instanceof Transform || expr instanceof NamedReference;\n}","tryCatchPattern":"try {\n  term = Spark3Util.toIcebergTerm(expr);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().startsWith(\"Cannot convert unknown expression\")) {\n    // extract column references from expr and retry\n  }\n}","preventionTips":["Pass column names/transforms, never computed expressions","Extract NamedReferences from complex expressions before conversion","Reject non-reference expressions early in DDL tooling"],"tags":["spark","expressions","conversion"],"backgroundTag":"incompatible-source-type","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"}