apache/iceberg · warning

Unsupported runtime filter

Error message

Unsupported runtime filter {}

What it means

SparkV2Filters.convert returned null because the runtime predicate kind is not representable as an Iceberg expression (unsupported function or literal type). SparkBatchQueryScan logs and skips that filter rather than failing the query. Performance-only impact: fewer predicates are pushed into the Iceberg scan.

Solutions

1. No action needed for correctness; the filter is evaluated elsewhere in Spark.
2. Check which predicate was logged and whether it can be expressed as a supported Iceberg filter.
3. Upgrade the Iceberg Spark runtime to a version supporting the predicate.

if (SparkV2Filters.convert(predicate) == null) { /* predicate unsupported; don't expect pushdown */ }

When it happens

Trigger: A Spark runtime filter using an unsupported predicate shape (e.g. certain functions, non-convertible literals) is applied to an Iceberg batch scan via SupportsRuntimeFiltering.filter([]).

Common situations: Spark versions emitting newer runtime filter functions than the connector supports; user-defined or non-standard filters; dynamic partition pruning variants not in Iceberg's supported set.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unsupported runtime filter
• Failed to bind to expected schema, skipping runtime filter
• Unsupported runtime filter
• Unsupported runtime filter
• Cannot add column since setting default values in Spark is…

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/source/SparkBatchQueryScan.java:208

    return ContentFileUtil.isFileScoped(deleteFile);
  }

  // at this moment, Spark can only pass IN filters for a single attribute
  // if there are multiple filter attributes, Spark will pass two separate IN filters
  private Expression convertRuntimeFilters(Predicate[] predicates) {
    Expression runtimeFilterExpr = Expressions.alwaysTrue();

    for (Predicate predicate : predicates) {
      Expression expr = SparkV2Filters.convert(predicate);
      if (expr != null) {
        try {
          Binder.bind(expectedSchema().asStruct(), expr, caseSensitive());
          runtimeFilterExpr = Expressions.and(runtimeFilterExpr, expr);
        } catch (ValidationException e) {
          LOG.warn("Failed to bind {} to expected schema, skipping runtime filter", expr, e);
        }
      } else {
        LOG.warn("Unsupported runtime filter {}", predicate);
      }
    }

    return runtimeFilterExpr;
  }

  @Override
  public Statistics estimateStatistics() {
    if (scan() == null) {
      return estimateStatistics(null);

    } else if (snapshotId != null) {
      Snapshot snapshot = table().snapshot(snapshotId);
      return estimateStatistics(snapshot);

    } else if (asOfTimestamp != null) {
      long snapshotIdAsOfTime = SnapshotUtil.snapshotIdAsOfTime(table(), asOfTimestamp);
      Snapshot snapshot = table().snapshot(snapshotIdAsOfTime);

View on GitHub (pinned to 86d9c8fc54)