apache/iceberg · error · UncheckedIOException

Failed to close changelog scan: ${scan}

Error message

Failed to close changelog scan: ${scan}

What it means

SparkChangelogScan.taskGroups wraps IOException raised while closing the CloseableIterable returned by scan.planTasks() in an UncheckedIOException. The scan planning itself succeeded, but closing the planning resources (manifest readers/file handles) failed.

Source

Thrown at spark/v4.2/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 chained IOException cause for the storage-level close failure
2. Check object store/filesystem health and retry the query
3. Use a more robust FileIO (e.g. S3FileIO with retries) if HDFS close failures recur
4. Report persistent close failures during planTasks to the Iceberg project

try { taskGroups() } catch (UncheckedIOException e) { log(e.getCause()); retry scan planning with backoff }

When it happens

Trigger: planTasks() iterable close() throws IOException during lazy task-group materialization of a changelog scan.

Common situations: Underlying FileIO (HDFS/S3) errors while releasing manifest readers; network interruption during close of open file handles; container-level cleanup failure.

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

• Table refresh failed
• Deleted rows scan task is not supported yet
• Unsupported changelog scan task type: ${task.getClass().getN
• Failed to close changelog scan: ${scan}
• Failed writing offset to: ${initialOffsetLocation}

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