apache/iceberg · error · IllegalArgumentException

Cannot parse predicates in where option

Error message

Cannot parse predicates in where option: ${where}

What it means

BaseProcedure.filterExpression converts a user-supplied 'where' predicate string into an Iceberg Expression. It first asks Spark to parse and resolve the SQL expression; if Spark raises AnalysisException (unparseable or unresolvable predicate), it rethrows as IllegalArgumentException. The error means the procedure's where option is not a valid, resolvable SQL predicate.

Solutions

1. Validate the predicate runs as a plain Spark query first: SELECT count(*) FROM tbl WHERE <predicate>.
2. Cast literal types explicitly, e.g. ts > cast('2024-01-01' as timestamp).
3. Fully qualify column names if the predicate needs disambiguation.
4. Quote identifiers containing special characters with backticks.

Example fix

-- before
CALL iceberg.system.expire_snapshots(table => 'db.t', where => "ts > '2024-01-01'");
-- after
CALL iceberg.system.expire_snapshots(table => 'db.t', where => "ts > cast('2024-01-01' as timestamp)");

spark.sql(s"SELECT 1 FROM $table WHERE $where").limit(1).collect() // dry-run the predicate

try { CALL ... where => "..."; } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Cannot parse predicates")) { /* fix predicate */ } else throw e; }

When it happens

Trigger: Passing where => "ts > '2024-01-01'" where the column doesn't exist, types don't match, syntax is invalid, or the predicate references columns/relations Spark cannot resolve during collectResolvedSparkExpression.

Common situations: Comparing a timestamp column with a non-castable string; using functions unsupported in the resolved context; referencing partition/column names with wrong case or quoting; typos like where => "a == 1 AND".

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Cannot parse predicates in where option:
• Cannot convert predicate to SQL:
• Cannot parse predicates in where option:
• Already closed files for partition:
• ALTER TABLE contains multiple distribution clauses

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/procedures/BaseProcedure.java:198

    String tableName = Spark3Util.quotedFullIdentifier(tableCatalog().name(), tableIdent);
    return spark().read().options(options).table(tableName);
  }

  protected void refreshSparkCache(Identifier ident, Table table) {
    CacheManager cacheManager = spark.sharedState().cacheManager();
    DataSourceV2Relation relation =
        DataSourceV2Relation.create(table, Option.apply(tableCatalog), Option.apply(ident));
    cacheManager.recacheByPlan(spark, relation);
  }

  protected Expression filterExpression(Identifier ident, String where) {
    try {
      String name = Spark3Util.quotedFullIdentifier(tableCatalog.name(), ident);
      org.apache.spark.sql.catalyst.expressions.Expression expression =
          SparkExpressionConverter.collectResolvedSparkExpression(spark, name, where);
      return SparkExpressionConverter.convertToIcebergExpression(expression);
    } catch (AnalysisException e) {
      throw new IllegalArgumentException("Cannot parse predicates in where option: " + where, e);
    }
  }

  protected InternalRow newInternalRow(Object... values) {
    return new GenericInternalRow(values);
  }

  protected static class Result implements LocalScan {
    private final StructType readSchema;
    private final InternalRow[] rows;

    public Result(StructType readSchema, InternalRow[] rows) {
      this.readSchema = readSchema;
      this.rows = rows;
    }

    @Override
    public StructType readSchema() {

View on GitHub (pinned to 86d9c8fc54)