apache/iceberg · error · UncheckedIOException

Failed to close changelog scan:

Error message

Failed to close changelog scan: 

What it means

Wrapping error in SparkChangelogScan.taskGroups: while draining scan.planTasks() into a list inside try-with-resources, an IOException from closing (or reading) the task-groups iterable is rethrown as UncheckedIOException with this message. The chained cause identifies the underlying file/stream failure during changelog planning.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/source/SparkChangelogScan.java:121

  @Override
  public Batch toBatch() {
    return new SparkBatch(
        sparkContext,
        table,
        null != scan ? scan.fileIO() : table::io,
        readConf,
        EMPTY_GROUPING_KEY_TYPE,
        taskGroups(),
        projection,
        hashCode());
  }

  private List<ScanTaskGroup<ChangelogScanTask>> taskGroups() {
    if (taskGroups == null) {
      try (CloseableIterable<ScanTaskGroup<ChangelogScanTask>> groups = scan.planTasks()) {
        this.taskGroups = Lists.newArrayList(groups);
      } catch (IOException e) {
        throw new UncheckedIOException("Failed to close changelog scan: " + scan, e);
      }
    }

    return taskGroups;
  }

  @Override
  public String description() {
    return String.format(
        Locale.ROOT,
        "IcebergChangelogScan(table=%s, fromSnapshotId=%d, toSnapshotId=%d, filters=%s)",
        table,
        startSnapshotId,
        endSnapshotId,
        filtersDesc());
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the caused-by chain for the underlying IOException
2. Retry the query; configure retries on the object store client
3. Verify FileIO credentials and network access
4. Check metadata file integrity

// pre-check storage reachability
fileIO.tableOps(); // or probe metadata json location before planning

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

When it happens

Trigger: IOException thrown by the underlying FileIO while planning or closing changelog task groups (manifest/IO failures, network to object store).

Common situations: S3/GCS/HDFS transient failures during scan planning; credentials expiry; corrupted metadata files.

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 scan: " + 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/e90fc8a7966881a0. Report an issue: GitHub.