apache/iceberg · error · IllegalArgumentException

Cannot parse type as a reference: " + type

Error message

Cannot parse type as a reference: " + type

What it means

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.

Source

Thrown at core/src/main/java/org/apache/iceberg/expressions/ExpressionParser.java:418

    }
  }

  @SuppressWarnings("unchecked")
  private static <T> UnboundTerm<T> term(JsonNode node) {
    if (node.isTextual()) {
      return Expressions.ref(node.asText());
    } else if (node.isObject()) {
      String type = JsonUtil.getString(TYPE, node);
      switch (type) {
        case REFERENCE:
          return Expressions.ref(JsonUtil.getString(TERM, node));
        case TRANSFORM:
          UnboundTerm<T> child = term(JsonUtil.get(TERM, node));
          String transform = JsonUtil.getString(TRANSFORM, node);
          return (UnboundTerm<T>)
              Expressions.transform(child.ref().name(), Transforms.fromString(transform));
        default:
          throw new IllegalArgumentException("Cannot parse type as a reference: " + type);
      }
    }

    throw new IllegalArgumentException(
        "Cannot parse reference (requires string or object): " + node);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg library to match the producer's version.
2. 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).
3. Regenerate the expression JSON with a supported version instead of editing by hand.

Example fix

// before
// {"type":"bogus-term","term":"col"}
Term t = Expressions.parser().fromJson(json);
// after
// "col" or {"type":"transform","transform":"truncate[10]","term":"col"}
Term t = Expressions.parser().fromJson(json);

if (termNode.isObject()) {
  String type = JsonUtil.getString("type", termNode);
  if (!Set.of("transform").contains(type)) throw new IllegalArgumentException("unknown term type: " + type);
}

boolean knownTermType(JsonNode n) { return n.isTextual() || (n.isObject() && n.hasNonNull("type") && "transform".equals(n.get("type").asText())); }

try {
  Term t = Expressions.parser().fromJson(json);
} catch (IllegalArgumentException e) {
  LOG.error("unrecognized term type in expression JSON", e);
  throw e;
}

When it happens

Trigger: 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.

Common situations: Forward-compatibility gaps reading expressions written by newer releases; typo in hand-written expression JSON.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unsupported operation: " + op
• Cannot convert JSON to literal: " + node
• Cannot parse reference (requires string or object): " + node
• Unknown task type:
• Cannot parse type from json:

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/d9ff46ae3c348d07. Report an issue: GitHub.