{"record":{"id":"6e42224ad43f85b8","repo":"apache/seatunnel","slug":"file-scan-split-failed","errorCode":"FILE_SCAN_SPLIT_FAILED","errorMessage":"Failed to scan iceberg splits from: ","messagePattern":"Failed to scan iceberg splits from: ","errorType":"error_code","errorClass":"IcebergConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/enumerator/scan/IcebergScanSplitPlanner.java","lineNumber":182,"sourceCode":"                throw new IcebergConnectorException(\n                        CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION,\n                        \"Unsupported stream scan strategy: \"\n                                + icebergScanContext.getStreamScanStrategy());\n        }\n    }\n\n    public static List<IcebergFileScanTaskSplit> planSplits(\n            Table table, IcebergScanContext context) {\n        try (CloseableIterable<CombinedScanTask> tasksIterable = planTasks(table, context)) {\n            List<IcebergFileScanTaskSplit> splits = new ArrayList<>();\n            for (CombinedScanTask combinedScanTask : tasksIterable) {\n                for (FileScanTask fileScanTask : combinedScanTask.files()) {\n                    splits.add(new IcebergFileScanTaskSplit(context.getTablePath(), fileScanTask));\n                }\n            }\n            return splits;\n        } catch (IOException e) {\n            throw new IcebergConnectorException(\n                    IcebergConnectorErrorCode.FILE_SCAN_SPLIT_FAILED,\n                    \"Failed to scan iceberg splits from: \" + table.name(),\n                    e);\n        }\n    }\n\n    private static CloseableIterable<CombinedScanTask> planTasks(\n            Table table, IcebergScanContext context) {\n        if (context.isStreaming()\n                || context.getStartSnapshotId() != null\n                || context.getEndSnapshotId() != null) {\n            IncrementalAppendScan scan = table.newIncrementalAppendScan();\n            scan = rebuildScanWithBaseConfig(scan, context);\n            if (context.getStartSnapshotId() != null) {\n                scan = scan.fromSnapshotExclusive(context.getStartSnapshotId());\n            }\n            if (context.getEndSnapshotId() != null) {\n                scan = scan.toSnapshot(context.getEndSnapshotId());","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/enumerator/scan/IcebergScanSplitPlanner.java#L164-L200","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the cause chain for the underlying IOException — usually a missing metadata file or unreachable storage; fix storage access first","Verify warehouse config and that the table's metadata files still exist (don't expire snapshots below the job's start snapshot while streaming)","Validate credentials/permissions for the file system used (s3a keys, HDFS user, Kerberos TGT)","Restart from a newer snapshot if the referenced metadata was garbage-collected"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight: confirm metadata location is readable\n// table.refresh(); table.currentSnapshot().manifestListLocation() -> verify readable via your fileIO","typeGuard":null,"tryCatchPattern":"try { planSplits(); } catch (IcebergConnectorException e) { if (e.getSeaTunnelErrorCode() == FILE_SCAN_SPLIT_FAILED) { /* check cause, retry with backoff */ } throw e; }","preventionTips":["Avoid expire_snapshots that remove snapshots referenced by running jobs","Verify HDFS/S3 access and credentials cluster-wide","Set snapshot retention longer than streaming job recovery windows","Monitor storage availability before checkpoints"],"tags":["iceberg","io","split-planning"],"backgroundTag":"file-read-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}