apache/iceberg · info

Unsupported runtime filter

Error message

Unsupported runtime filter {}

What it means

SparkCopyOnWriteScan receives Spark runtime filters and tries to convert them to Iceberg expressions for task filtering; unsupported predicates are logged with this warning and skipped. The scan proceeds without that filter's benefit.

Solutions

1. Confirm the filter shape is one SparkV2Filters supports (simple column comparisons/IN)
2. Rewrite the statement so runtime filter keys are plain columns
3. Treat as informational unless scan performance regresses

When it happens

Trigger: filter() is called by Spark with a runtime predicate whose type SparkV2Filters.convert cannot translate (returns null).

Common situations: Runtime bloom/dynamic-pruning filters on complex expressions; CopL/CopU scans in MERGE/UPDATE/DELETE plans where Spark emits filter variants Iceberg doesn't map.

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
• Failed to bind to expected schema, skipping runtime filter

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

Appendix: source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/source/SparkCopyOnWriteScan.java:156

        // so filter files only if it is beneficial
        if (filteredLocations == null || fileLocations.size() < filteredLocations.size()) {
          this.filteredLocations = fileLocations;
          List<FileScanTask> filteredTasks =
              tasks().stream()
                  .filter(file -> fileLocations.contains(file.file().location()))
                  .collect(Collectors.toList());

          LOG.info(
              "{} of {} task(s) for table {} matched runtime file filter with {} location(s)",
              filteredTasks.size(),
              tasks().size(),
              table().name(),
              fileLocations.size());

          resetTasks(filteredTasks);
        }
      } else {
        LOG.warn("Unsupported runtime filter {}", predicate);
      }
    }
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) {
      return true;
    }

    if (o == null || getClass() != o.getClass()) {
      return false;
    }

    SparkCopyOnWriteScan that = (SparkCopyOnWriteScan) o;
    return table().name().equals(that.table().name())
        && readSchema().equals(that.readSchema()) // compare Spark schemas to ignore field ids
        && filterExpressions().toString().equals(that.filterExpressions().toString())

View on GitHub (pinned to 86d9c8fc54)