apache/iceberg · error · ValidationException

Invalid value for conversion to type %s: %s (%s)

Error message

Invalid value for conversion to type %s: %s (%s)

What it means

During bindLiteralOperation, the literal is converted to the bound term's type via literal().to(type). If the conversion returns null — meaning the value cannot be represented in the target type and is not the aboveMax/belowMin sentinel — binding fails with this ValidationException reporting the target type, the value, and its Java class.

Source

Thrown at api/src/main/java/org/apache/iceberg/expressions/UnboundPredicate.java:182

  }

  private boolean floatingType(Type.TypeID typeID) {
    return Type.TypeID.DOUBLE.equals(typeID) || Type.TypeID.FLOAT.equals(typeID);
  }

  private Expression bindLiteralOperation(BoundTerm<T> boundTerm) {
    if (op() == Operation.STARTS_WITH || op() == Operation.NOT_STARTS_WITH) {
      ValidationException.check(
          boundTerm.type().equals(Types.StringType.get()),
          "Term for STARTS_WITH or NOT_STARTS_WITH must produce a string: %s: %s",
          boundTerm,
          boundTerm.type());
    }

    Literal<T> lit = literal().to(boundTerm.type());

    if (lit == null) {
      throw new ValidationException(
          "Invalid value for conversion to type %s: %s (%s)",
          boundTerm.type(), literal().value(), literal().value().getClass().getName());

    } else if (lit == Literals.aboveMax()) {
      switch (op()) {
        case LT:
        case LT_EQ:
        case NOT_EQ:
          return Expressions.alwaysTrue();
        case GT:
        case GT_EQ:
        case EQ:
          return Expressions.alwaysFalse();
      }
    } else if (lit == Literals.belowMin()) {
      switch (op()) {
        case GT:
        case GT_EQ:

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the column type (schema.findType(name)) and construct the literal with the matching Java type before filtering
2. Pre-validate the value fits the target type's range/precision (e.g. value fits int, decimal scale/precision match)
3. Catch ValidationException around bind/filter and surface a user-friendly type error
4. Fix the query to use a value compatible with the column type

Example fix

// before
Expression e = Expressions.equal("int_col", 99999999999L); // cannot convert to int
// after
Type t = schema.findType("int_col");
long v = 99999999999L;
Expression e = (t.typeId() == Type.TypeID.INTEGER)
    ? Expressions.equal("int_col", (int) v) // ensure it fits, or reject earlier
    : Expressions.equal("int_col", v);

Type t = schema.findType(name);
// verify the literal's Java value is representable in t before building the predicate

try { table.filter(expr); } catch (ValidationException e) { /* report incompatible literal for column type to the user */ }

When it happens

Trigger: Binding a predicate whose literal cannot be converted to the column type: e.g. comparing a long literal that overflows an int column in a way that produces no conversion, a string literal to a numeric column where conversion is undefined, or a decimal literal to an incompatible type.

Common situations: Engine-generated filters passing wrong-typed literals (string vs numeric); schema evolution changing column types so old hardcoded filter values no longer convert; user API queries filtering a long column with a value beyond the column's precision.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• IsNaN cannot be used with a non-floating-point column
• NotNaN cannot be used with a non-floating-point column
• Operation must be IS_NULL, NOT_NULL, IS_NAN, or NOT_NAN
• Visitor %s does not support non-reference: %s
• Cannot change the type of BelowMin

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