apache/seatunnel · error · SeaTunnelRuntimeException

FILE_SPLIT_SIZE_ILLEGAL

FILE_SPLIT_SIZE_ILLEGAL

Error message

file_split_size must be greater than 0 when enable_file_split=true, but got: %d

What it means

ParquetFileSplitStrategy's single-argument constructor validates that the split size in bytes is strictly positive, since parquet chunking cannot proceed with a zero/negative chunk size. A non-positive value raises FILE_SPLIT_SIZE_ILLEGAL via SeaTunnelRuntimeException.

Source

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

 * FileSourceSplit}s by merging one or more contiguous RowGroups according to the configured split
 * size. A split will never break a RowGroup, ensuring correctness and compatibility with Parquet
 * readers.
 *
 * <p>The generated split range ({@code start}, {@code length}) represents a byte range covering
 * complete RowGroups. The actual row-level reading and decoding are delegated to the Parquet reader
 * implementation.
 *
 * <p>This design enables efficient parallel reading of Parquet files while preserving Parquet
 * format semantics and avoiding invalid byte-level splits.
 */
public class ParquetFileSplitStrategy implements FileSplitStrategy, Closeable {

    private final long splitSizeBytes;
    private final HadoopFileSystemProxy hadoopFileSystemProxy;

    public ParquetFileSplitStrategy(long splitSizeBytes) {
        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 = null;
    }

    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;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Pass a positive byte size, e.g. new ParquetFileSplitStrategy(134217728).
2. Fix the upstream file_split_size config to be > 0.
3. If constructing programmatically, validate/guard the value before invoking the constructor.
4. Remove the splitting strategy entirely if whole-file reads suffice.

Example fix

// before
new ParquetFileSplitStrategy(0)
// after
new ParquetFileSplitStrategy(134217728L)

if (splitSizeBytes <= 0) throw new IllegalArgumentException("ParquetFileSplitStrategy requires splitSizeBytes > 0");
new ParquetFileSplitStrategy(splitSizeBytes);

boolean isValidSplitSize(long bytes) { return bytes > 0; }

try { strategy = new ParquetFileSplitStrategy(size); } catch (SeaTunnelRuntimeException e) { if (e.getSeaTunnelErrorCode() == FileConnectorErrorCode.FILE_SPLIT_SIZE_ILLEGAL) { /* correct size or skip splitting */ } throw e; }

When it happens

Trigger: Code constructs new ParquetFileSplitStrategy(splitSizeBytes) with splitSizeBytes <= 0 — typically a misconfigured or defaulted FILE_SPLIT_SIZE value propagated from source config.

Common situations: Programmatic use of the split strategy with an uninitialized long (0); config where file_split_size was omitted or set to a negative number; template substitution failures.

Related errors

• FILE_SPLIT_SIZE_ILLEGAL
• FILE_SPLIT_FAIL
• ILLEGAL_ARGUMENT
• Condition operator must not be null
• Invalid metalake table id:

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