apache/seatunnel · error · SeaTunnelRuntimeException

Split file for [%s] failed, cause=%s: %s

Error message

Split file for [%s] failed, cause=%s: %s

What it means

AccordingToSplitSizeSplitStrategy.split divides a file into fixed-size splits using HDFS file status and positioned reads. Any IOException during splitting (file status, stream open/read) is mapped via mapToRuntimeException into a SeaTunnelRuntimeException: 'Split file for [path] failed, cause=...' so users get the offending path and cause instead of a raw Hadoop stack trace.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/split/AccordingToSplitSizeSplitStrategy.java:122

                            new FileSourceSplit(
                                    tableId,
                                    normalizedPath,
                                    currentStart,
                                    fileSize - currentStart));
                    break;
                }
                long actualEnd = findNextDelimiterWithSeek(input, tentativeEnd, fileSize);
                if (actualEnd <= currentStart) {
                    actualEnd = tentativeEnd;
                }
                splits.add(
                        new FileSourceSplit(
                                tableId, normalizedPath, currentStart, actualEnd - currentStart));
                currentStart = actualEnd;
            }
            return splits;
        } catch (IOException e) {
            throw mapToRuntimeException(normalizedPath, "Split file", e);
        }
    }

    private long safeGetFileSize(String filePath) {
        try {
            return hadoopFileSystemProxy.getFileStatus(filePath).getLen();
        } catch (IOException e) {
            throw mapToRuntimeException(filePath, "Get file status", e);
        }
    }

    private static SeaTunnelRuntimeException mapToRuntimeException(
            String filePath, String operation, IOException e) {
        IOException unwrapped = unwrapRemoteException(e);
        FileConnectorErrorCode errorCode = mapIOExceptionToErrorCode(unwrapped);
        String message =
                String.format(
                        "%s for [%s] failed, cause=%s: %s",

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the file exists and is readable at the reported path (hdfs dfs -ls / gsutil ls, etc.)
2. Check Hadoop filesystem connectivity/credentials (Kerberos token, service account) at split time
3. Re-run the job; transient storage/network outages are a common cause
4. Check that the file was not truncated/deleted between listing and splitting (upstream writer still in progress)

Example fix

// before: file deleted mid-job
path = gs://bucket/report.csv (removed by upstream job)
// after: keep upstream writers from deleting; or point to a stable snapshot
path = gs://bucket/snapshot=2026-09-10/report.csv

// verify readability before job submission
Files.exists(localPath) || hadoopFs.exists(new org.apache.hadoop.fs.Path(normalizedPath))

static boolean fileExists(HadoopFileSystemProxy fs, String p) {
    try { return fs.getFileStatus(p) != null; } catch (IOException e) { return false; }
}

try {
    List<FileSourceSplit> splits = strategy.split(context);
} catch (SeaTunnelRuntimeException e) {
    logger.error("splitting failed; check path/permissions/storage", e);
    throw e; // split failure is unrecoverable in-task
}

When it happens

Trigger: An IOException thrown while computing splits — the underlying file disappearing between enumeration and split, permission errors reading the file, a namenode/storage outage, or network I/O failure while reading region boundaries.

Common situations: See trigger scenarios.

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

• Circular condition chain detected: '%s' already exists in th
• Condition for option '%s' has a null operator
• Failed during source_listing setup/scan for protocol=%s, pat
• SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED
• COMMON_ERROR_CODE-14

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