apache/iceberg · info

Unsupported runtime filter

Error message

Unsupported runtime filter {}

What it means

A runtime filter predicate could not be converted to an Iceberg Expression by SparkV2Filters (returned null), so it cannot be pushed into the scan and is skipped with this warning. The query is unaffected except for losing that filter's pruning benefit.

Solutions

1. Check the logged predicate and confirm it's a filter Iceberg supports converting
2. Ensure join/filter keys are simple columns to enable supported runtime filters
3. Ignore if performance is acceptable; it's a skipped optimization, not a failure

When it happens

Trigger: Spark passes a runtime filter type (e.g. certain IN/bloom-filter predicates) that SparkV2Filters.convert does not support.

Common situations: Dynamic partition pruning or runtime bloom filters on expressions Iceberg's converter doesn't handle, often with non-trivial join keys or specific Spark versions/features.

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/123e420ecba666fb. Report an issue: GitHub.

Appendix: source

Thrown at spark/v3.5/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)