What causes "Number of input splits has to be at least 1." in apache/flink?

Ensure the source operator and environment parallelism are >= 1; check env.getParallelism() and any setParallelism(...) calls on the data source.

apache/flink · error · IllegalArgumentException

Number of input splits has to be at least 1.

Error message

Number of input splits has to be at least 1.

What it means

Thrown by FileInputFormat.createInputSplits(int minNumSplits) when the requested minimum number of file splits is less than 1. The method computes splits by dividing file blocks; at least one split is always required to process data. This is an input contract violation: a job with zero or negative effective parallelism cannot read its input.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/io/FileInputFormat.java:536

    @Override
    public LocatableInputSplitAssigner getInputSplitAssigner(FileInputSplit[] splits) {
        return new LocatableInputSplitAssigner(splits);
    }

    /**
     * Computes the input splits for the file. By default, one file block is one split. If more
     * splits are requested than blocks are available, then a split may be a fraction of a block and
     * splits may cross block boundaries.
     *
     * @param minNumSplits The minimum desired number of file splits.
     * @return The computed file splits.
     * @see org.apache.flink.api.common.io.InputFormat#createInputSplits(int)
     */
    @Override
    public FileInputSplit[] createInputSplits(int minNumSplits) throws IOException {
        if (minNumSplits < 1) {
            throw new IllegalArgumentException("Number of input splits has to be at least 1.");
        }

        // take the desired number of splits into account
        minNumSplits = Math.max(minNumSplits, this.numSplits);

        final List<FileInputSplit> inputSplits = new ArrayList<FileInputSplit>(minNumSplits);

        // get all the files that are involved in the splits
        List<FileStatus> files = new ArrayList<>();
        long totalLength = 0;

        for (Path path : getFilePaths()) {
            final FileSystem fs = path.getFileSystem();
            final FileStatus pathFile = fs.getFileStatus(path);

            if (pathFile.isDir()) {
                totalLength += addFilesInDir(path, files, true);
            } else {

View on GitHub (pinned to 2f3c205e92)

Solutions

Ensure the source operator and environment parallelism are >= 1; check env.getParallelism() and any setParallelism(...) calls on the data source.
If you call createInputSplits directly (rare, custom execution), pass a positive int such as Math.max(1, desiredSplits).
Audit the job graph / ExecutionConfig to confirm no component overrides parallelism to 0 for this operator.

Example fix

// before
env.setParallelism(0);
DataSet<String> data = env.readFile(format, path);

// after
env.setParallelism(4);
DataSet<String> data = env.readFile(format, path);

Defensive patterns

Strategy: validation

Validate before calling

// Validate parallelism/split count before the job runs
int parallelism = env.getParallelism();
if (parallelism < 1) {
    throw new IllegalStateException("Job parallelism must be >= 1 for file sources, got " + parallelism);
}
// If invoking createInputSplits directly:
int minSplits = Math.max(1, desiredSplits);
FileInputSplit[] splits = format.createInputSplits(minSplits);

Prevention

Never set env or source parallelism to 0.
Assert env.getParallelism() >= 1 in a pre-submit hook.
When calling createInputSplits directly, clamp the value with Math.max(1, n).

When it happens

Trigger: Calling createInputSplits(0) or with a negative value. In practice the framework derives minNumSplits from the source operator's parallelism, so this fires when job parallelism resolves to less than 1, when an InputFormatSourceFunction is wired with parallelism 0, or when a custom InputFormat implementation forwards a bad split count.

Common situations: Setting execution environment parallelism to 0 via env.setParallelism(0); a DataSource with a degenerate parallelism config; unit tests that invoke createInputSplits directly with a placeholder value of 0; programmatic graph builders that miscompute subtask counts.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/8d538ce1cb252e81. Report an issue: GitHub.