apache/seatunnel · error · SeaTunnelRuntimeException

FILE_SPLIT_FAIL

FILE_SPLIT_FAIL

Error message

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

What it means

Parquet file splitting failed in ParquetFileSplitStrategy. The strategy reads the Parquet footer to enumerate row groups and turn them into FileSourceSplits; any IOException during that I/O (unreadable file, corrupt footer, network filesystem hiccup) is wrapped in SeaTunnelRuntimeException with code FILE_SPLIT_FAIL. The original exception class and message are preserved in the message.

Source

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

    public ParquetFileSplitStrategy(long splitSizeBytes, HadoopConf hadoopConf) {
        if (splitSizeBytes <= 0) {
            throw new SeaTunnelRuntimeException(
                    FileConnectorErrorCode.FILE_SPLIT_SIZE_ILLEGAL,
                    String.format(
                            "file_split_size must be greater than 0 when enable_file_split=true, but got: %d",
                            splitSizeBytes));
        }
        this.splitSizeBytes = splitSizeBytes;
        this.hadoopFileSystemProxy = new HadoopFileSystemProxy(hadoopConf);
    }

    @Override
    public List<FileSourceSplit> split(String tableId, String filePath) {
        try {
            return splitByRowGroups(tableId, filePath, readRowGroups(filePath));
        } catch (IOException e) {
            throw new SeaTunnelRuntimeException(
                    FileConnectorErrorCode.FILE_SPLIT_FAIL,
                    String.format(
                            "Split parquet file for [%s] failed, cause=%s: %s",
                            filePath, e.getClass().getSimpleName(), e.getMessage()),
                    e);
        }
    }

    /**
     * Core split logic based on row group metadata. This method is IO-free and unit-test friendly.
     */
    List<FileSourceSplit> splitByRowGroups(
            String tableId, String filePath, List<BlockMetaData> rowGroups) {
        List<FileSourceSplit> splits = new ArrayList<>();
        if (rowGroups == null || rowGroups.isEmpty()) {
            return splits;
        }
        long currentStart = 0;

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the 'cause=...' part of the message and the wrapped exception to see the root IOException; fix that issue first
  2. Verify the path exists, is a readable file, and is a valid Parquet file (e.g. open it with parquet-tools / pyarrow)
  3. Confirm the filesystem/credentials config (HDFS namenode, S3 endpoint/AK/SK) is correct
  4. If the file is still being written, exclude it or wait for the writer to complete before running the job
  5. Re-run the job if the cause was a transient network failure

Example fix

// before
String path = "/data/export/events"; // missing .parquet, actually a directory
// after
String path = "/data/export/events.parquet"; // verified: exists, readable, valid parquet
Defensive patterns

Strategy: validation

Validate before calling

// Java (Hadoop FileSystem available)
FileSystem fs = new Path(filePath).getFileSystem(conf);
if (!fs.exists(new Path(filePath))) throw new IllegalArgumentException("missing file: " + filePath);
FileStatus st = fs.getFileStatus(new Path(filePath));
if (st.isDirectory()) throw new IllegalArgumentException("not a file: " + filePath);
if (st.getLen() < 8) throw new IllegalArgumentException("too small to be parquet: " + filePath);

Try / catch

try {
    strategy.split(tableId, filePath);
} catch (SeaTunnelRuntimeException e) {
    if (FileConnectorErrorCode.FILE_SPLIT_FAIL.equals(e.getErrorCode())) {
        LOG.warn("Skipping unreadable parquet file {}: {}", filePath, e.getCause());
    } else { throw e; }
}

Prevention

When it happens

Trigger: Calling split(tableId, filePath) when readRowGroups(filePath) throws IOException: the file does not exist or is inaccessible, the path is a directory, the file is not valid Parquet (missing/corrupt footer), or reading from remote storage (HDFS/S3) fails mid-read.

Common situations: Configured path typo or bucket/permission mistake; file truncated or still being written by an upstream job; non-Parquet file with .parquet extension; Hadoop/Parquet version incompatibility corrupting footer parsing; transient S3/HDFS connectivity failures.

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

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