What causes "Cannot parse predicates in where option: ${where}" in apache/iceberg?

Test the predicate standalone: `SELECT count(*) FROM tbl WHERE ` to confirm it analyzes.

apache/iceberg · error · IllegalArgumentException

Cannot parse predicates in where option: ${where}

Error message

Cannot parse predicates in where option: ${where}

What it means

Procedures accepting a `where` option resolve it by collecting a resolved Spark expression through SQL analysis. If analysis throws AnalysisException, BaseProcedure rethrows it as an IllegalArgumentException saying the predicates in the where option cannot be parsed, including the offending `where` string.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/procedures/BaseProcedure.java:182

    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 abstract static class Builder<T extends BaseProcedure> implements ProcedureBuilder {
    private TableCatalog tableCatalog;

    @Override
    public Builder<T> withTableCatalog(TableCatalog newTableCatalog) {
      this.tableCatalog = newTableCatalog;
      return this;
    }

    @Override
    public T build() {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Test the predicate standalone: `SELECT count(*) FROM tbl WHERE <predicate>` to confirm it analyzes.
Use single quotes for string literals and valid Spark SQL syntax.
Verify column names/types with DESCRIBE TABLE before building the predicate.
Catch IllegalArgumentException around the CALL and surface the where string for correction.

Example fix

// before
CALL cat.sys.expire_snapshots(table => 't', where => "ts > \"2024-01-01\"")
// after
CALL cat.sys.expire_snapshots(table => 't', where => "ts > '2024-01-01'")

Defensive patterns

Strategy: validation

Validate before calling

// pre-flight: ensure the predicate analyzes against the table
spark.sql("SELECT 1 FROM " + fullTableName + " WHERE " + where).limit(1).collect();

Try / catch

try { spark.sql("CALL cat.sys.expire_snapshots(table => 't', where => \"ts > '2024-01-01'\")"); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Cannot parse predicates in where option")) { /* fix the where SQL */ } throw e; }

Prevention

Test the predicate in a standalone SELECT before using it in a procedure.
Use single quotes for string literals in Spark SQL.
Validate column names/types with DESCRIBE TABLE first.
Avoid dialect-specific syntax from other SQL engines.

When it happens

Trigger: Calling a procedure with `where => "..."` containing invalid SQL, unknown columns, unresolved functions, or dialect-mismatched expressions.

Common situations: Referencing columns not in the table; using non-Spark functions; double-quoted string literals; typos in column names; predicates copied from other SQL engines.

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

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