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

When enable_file_split=true, FILE_SPLIT_SIZE must be a positive byte value because it defines the size of each file chunk. The factory validates the configured value and throws FILE_SPLIT_SIZE_ILLEGAL (SeaTunnelRuntimeException) for zero or negative sizes.

Source

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

        CompressFormat compressCodec = readonlyConfig.get(FileBaseSourceOptions.COMPRESS_CODEC);
        ArchiveCompressFormat archiveCompressCodec =
                readonlyConfig.get(FileBaseSourceOptions.ARCHIVE_COMPRESS_CODEC);
        if (compressCodec != CompressFormat.NONE
                || archiveCompressCodec != ArchiveCompressFormat.NONE) {
            log.warn(
                    "enable_file_split=true but compress_codec={} or archive_compress_codec={} is not NONE. "
                            + "Falling back to non-splitting mode.",
                    compressCodec,
                    archiveCompressCodec);
            return new DefaultFileSplitStrategy();
        }

        Objects.requireNonNull(
                hadoopConf, "hadoopConf must not be null when file split is enabled");

        long fileSplitSize = readonlyConfig.get(FileBaseSourceOptions.FILE_SPLIT_SIZE);
        if (fileSplitSize <= 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",
                            fileSplitSize));
        }
        if (FileFormat.PARQUET == fileFormat) {
            return new ParquetFileSplitStrategy(fileSplitSize, hadoopConf);
        }
        String rowDelimiter =
                !readonlyConfig.getOptional(FileBaseSourceOptions.ROW_DELIMITER).isPresent()
                        ? DEFAULT_ROW_DELIMITER
                        : readonlyConfig.get(FileBaseSourceOptions.ROW_DELIMITER);
        long skipHeaderRowNumber =
                readonlyConfig.get(FileBaseSourceOptions.CSV_USE_HEADER_LINE)
                        ? 1L
                        : readonlyConfig.get(FileBaseSourceOptions.SKIP_HEADER_ROW_NUMBER);
        String encodingName = readonlyConfig.get(FileBaseSourceOptions.ENCODING);
        return new AccordingToSplitSizeSplitStrategy(

View on GitHub (pinned to cf67b549a7)

Solutions

Set file_split_size to a positive number of bytes, e.g. 134217728 (128MB).
Remove enable_file_split=true if whole-file reading is intended, which avoids needing file_split_size.
Verify the resolved value type is a plain long (no 'MB' suffix strings, which parse to 0).
Check for template placeholders rendering to 0 and fix the variable.

Example fix

// before
enable_file_split = true
file_split_size = 0
// after
enable_file_split = true
file_split_size = 134217728

Defensive patterns

Strategy: validation

Validate before calling

long size = readonlyConfig.get(FileBaseSourceOptions.FILE_SPLIT_SIZE);
if (enableFileSplit && size <= 0) throw new IllegalArgumentException("file_split_size must be > 0");

Try / catch

try { strategy = FileSplitStrategyFactory.initFileSplitStrategy(cfg, conf, format); } catch (SeaTunnelRuntimeException e) { if (e.getSeaTunnelErrorCode() == FileConnectorErrorCode.FILE_SPLIT_SIZE_ILLEGAL) { /* fix config or disable splitting */ } throw e; }

Prevention

Set file_split_size to a positive byte count whenever enable_file_split=true.
Never leave file_split_size at 0 or negative in templates.
Remember the value is plain bytes, not 'MB' strings.
Run config validation before submitting the job.

When it happens

Trigger: Config sets enable_file_split=true while file_split_size is 0, negative, or the option default resolves to a non-positive long when read via readonlyConfig.get(FileBaseSourceOptions.FILE_SPLIT_SIZE) in initFileSplitStrategy.

Common situations: Users forgetting to set file_split_size after enabling splitting; unit mistakes (writing '0' or a negative number); templating errors producing an empty/zero value.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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