apache/iceberg · error · UncheckedIOException

Failed to close scan: " + scan

Error message

Failed to close scan: " + scan

What it means

SparkPartitioningAwareScan.tasks converts IOException from closing/reading scan.planTasks() into UncheckedIOException, indicating batch scan planning failed while the task iterable was consumed or closed.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/source/SparkPartitioningAwareScan.java:197

  protected synchronized List<T> tasks() {
    if (tasks == null) {
      try (CloseableIterable<? extends ScanTask> taskIterable = scan.planFiles()) {
        List<T> plannedTasks = Lists.newArrayList();

        for (ScanTask task : taskIterable) {
          ValidationException.check(
              taskJavaClass().isInstance(task),
              "Unsupported task type, expected a subtype of %s: %s",
              taskJavaClass().getName(),
              task.getClass().getName());

          plannedTasks.add(taskJavaClass().cast(task));
        }

        this.tasks = plannedTasks;
      } catch (IOException e) {
        throw new UncheckedIOException("Failed to close scan: " + scan, e);
      }
    }

    return tasks;
  }

  @Override
  protected synchronized List<ScanTaskGroup<T>> taskGroups() {
    if (taskGroups == null) {
      if (groupingKeyType().fields().isEmpty()) {
        CloseableIterable<ScanTaskGroup<T>> plannedTaskGroups =
            TableScanUtil.planTaskGroups(
                CloseableIterable.withNoopClose(tasks()),
                adjustSplitSize(tasks(), scan.targetSplitSize()),
                scan.splitLookback(),
                scan.splitOpenFileCost());
        this.taskGroups = Lists.newArrayList(plannedTaskGroups);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Read the caused-by chain for the root IOException
2. Retry the query; add retry/throttling config on the storage client
3. Verify FileIO credentials and network reachability
4. Validate table metadata integrity (attempt a metadata table read)

// probe the table before planning
boolean reachable = fileIO.newInputFile(table.location() + "/metadata").exists();

try { scan.tasks(); } catch (UncheckedIOException e) { retryWithBackoff(e.getCause()); }

When it happens

Trigger: IOException from the underlying FileIO during batch scan planning (manifest reads, object store errors) surfaced when Spark plans the batch read.

Common situations: Object-store outages or throttling during query planning; expired credentials; corrupted manifest/metadata files; HDFS unavailability.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to close changelog scan:
• Unsupported task group for row-based reads: ${partition.task
• Failed to list partitions of table %s
• Failed to close changelog scan: ${scan}
• Failed to close scan: ${scan}

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