apache/seatunnel · error · IcebergConnectorException

FILE_SCAN_SPLIT_FAILED

FILE_SCAN_SPLIT_FAILED

Error message

Failed to scan iceberg splits from: 

What it means

planSplits() executes an Iceberg table scan and packages its FileScanTasks into SeaTunnel splits. If the scan/IO layer throws IOException while reading table metadata or opening tasks, it is wrapped as IcebergConnectorException(FILE_SCAN_SPLIT_FAILED) naming the table. It means split planning failed at the storage/metadata level, before any reader started.

Source

Thrown at seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/enumerator/scan/IcebergScanSplitPlanner.java:182

                throw new IcebergConnectorException(
                        CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION,
                        "Unsupported stream scan strategy: "
                                + icebergScanContext.getStreamScanStrategy());
        }
    }

    public static List<IcebergFileScanTaskSplit> planSplits(
            Table table, IcebergScanContext context) {
        try (CloseableIterable<CombinedScanTask> tasksIterable = planTasks(table, context)) {
            List<IcebergFileScanTaskSplit> splits = new ArrayList<>();
            for (CombinedScanTask combinedScanTask : tasksIterable) {
                for (FileScanTask fileScanTask : combinedScanTask.files()) {
                    splits.add(new IcebergFileScanTaskSplit(context.getTablePath(), fileScanTask));
                }
            }
            return splits;
        } catch (IOException e) {
            throw new IcebergConnectorException(
                    IcebergConnectorErrorCode.FILE_SCAN_SPLIT_FAILED,
                    "Failed to scan iceberg splits from: " + table.name(),
                    e);
        }
    }

    private static CloseableIterable<CombinedScanTask> planTasks(
            Table table, IcebergScanContext context) {
        if (context.isStreaming()
                || context.getStartSnapshotId() != null
                || context.getEndSnapshotId() != null) {
            IncrementalAppendScan scan = table.newIncrementalAppendScan();
            scan = rebuildScanWithBaseConfig(scan, context);
            if (context.getStartSnapshotId() != null) {
                scan = scan.fromSnapshotExclusive(context.getStartSnapshotId());
            }
            if (context.getEndSnapshotId() != null) {
                scan = scan.toSnapshot(context.getEndSnapshotId());

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the cause chain for the underlying IOException — usually a missing metadata file or unreachable storage; fix storage access first
2. Verify warehouse config and that the table's metadata files still exist (don't expire snapshots below the job's start snapshot while streaming)
3. Validate credentials/permissions for the file system used (s3a keys, HDFS user, Kerberos TGT)
4. Restart from a newer snapshot if the referenced metadata was garbage-collected

// Pre-flight: confirm metadata location is readable
// table.refresh(); table.currentSnapshot().manifestListLocation() -> verify readable via your fileIO

try { planSplits(); } catch (IcebergConnectorException e) { if (e.getSeaTunnelErrorCode() == FILE_SCAN_SPLIT_FAILED) { /* check cause, retry with backoff */ } throw e; }

When it happens

Trigger: IOException while reading Iceberg metadata files (manifests, manifest lists) or during combinedScanTask iteration — e.g. missing metadata file, unreachable HDFS/S3, permission errors, or large scan task opening failures.

Common situations: Warehouse path unreachable from the cluster (HDFS NameNode down, S3 endpoint/credentials wrong); metadata files deleted by table maintenance (expire_snapshots while a job references old snapshots); Kerberos/auth token expiry.

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 equality delta writer
• Error adding Hadoop resource {}, resource was not added
• Failed to read manifest {}, assuming files not yet committed
• Circular condition chain detected: '%s' already exists in th
• Condition for option '%s' has a null operator

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/6e42224ad43f85b8. Report an issue: GitHub.