{"record":{"id":"d9ff46ae3c348d07","repo":"apache/iceberg","slug":"cannot-parse-type-as-a-reference-type","errorCode":null,"errorMessage":"Cannot parse type as a reference: \" + type","messagePattern":"Cannot parse type as a reference: \" \\+ type","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/expressions/ExpressionParser.java","lineNumber":418,"sourceCode":"    }\n  }\n\n  @SuppressWarnings(\"unchecked\")\n  private static <T> UnboundTerm<T> term(JsonNode node) {\n    if (node.isTextual()) {\n      return Expressions.ref(node.asText());\n    } else if (node.isObject()) {\n      String type = JsonUtil.getString(TYPE, node);\n      switch (type) {\n        case REFERENCE:\n          return Expressions.ref(JsonUtil.getString(TERM, node));\n        case TRANSFORM:\n          UnboundTerm<T> child = term(JsonUtil.get(TERM, node));\n          String transform = JsonUtil.getString(TRANSFORM, node);\n          return (UnboundTerm<T>)\n              Expressions.transform(child.ref().name(), Transforms.fromString(transform));\n        default:\n          throw new IllegalArgumentException(\"Cannot parse type as a reference: \" + type);\n      }\n    }\n\n    throw new IllegalArgumentException(\n        \"Cannot parse reference (requires string or object): \" + node);\n  }\n}\n","sourceCodeStart":400,"sourceCodeEnd":426,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/expressions/ExpressionParser.java#L400-L426","documentation":"When parsing a term from JSON, ExpressionParser handles object-form terms of type \"transform\" (and reference forms); a term object whose \"type\" field is some other value falls through to this IllegalArgumentException. The JSON term type is unrecognized by this parser version.","triggerScenarios":"ExpressionParser.fromJson on a term object with an unknown \"type\" value — e.g. JSON from a newer Iceberg that added term types, or hand-edited metadata.","commonSituations":"Forward-compatibility gaps reading expressions written by newer releases; typo in hand-written expression JSON.","solutions":["Upgrade the Iceberg library to match the producer's version.","Check the \"type\" field of the term object in the JSON and correct it (must be a valid term type such as \"transform\", or omit the object form and use a plain string reference).","Regenerate the expression JSON with a supported version instead of editing by hand."],"exampleFix":"// before\n// {\"type\":\"bogus-term\",\"term\":\"col\"}\nTerm t = Expressions.parser().fromJson(json);\n// after\n// \"col\" or {\"type\":\"transform\",\"transform\":\"truncate[10]\",\"term\":\"col\"}\nTerm t = Expressions.parser().fromJson(json);","handlingStrategy":"validation","validationCode":"if (termNode.isObject()) {\n  String type = JsonUtil.getString(\"type\", termNode);\n  if (!Set.of(\"transform\").contains(type)) throw new IllegalArgumentException(\"unknown term type: \" + type);\n}","typeGuard":"boolean knownTermType(JsonNode n) { return n.isTextual() || (n.isObject() && n.hasNonNull(\"type\") && \"transform\".equals(n.get(\"type\").asText())); }","tryCatchPattern":"try {\n  Term t = Expressions.parser().fromJson(json);\n} catch (IllegalArgumentException e) {\n  LOG.error(\"unrecognized term type in expression JSON\", e);\n  throw e;\n}","preventionTips":["Keep producer and consumer Iceberg versions aligned.","Use string reference terms or standard transform objects only.","Regenerate JSON with ExpressionParser.toJson rather than hand-writing it."],"tags":["expressions","json","deserialization","forward-compatibility"],"backgroundTag":"invalid-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"}