What causes "The fetch size (%s) must be > 0, but is %d" in apache/flink?

Set StreamFormat.FETCH_IO_SIZE to a positive value, e.g. '1mb' or larger. The default is typically sufficient; remove the override if unsure.

apache/flink · error · IllegalConfigurationException

The fetch size (%s) must be > 0, but is %d

Error message

The fetch size (%s) must be > 0, but is %d

What it means

StreamFormatAdapter.openStream reads StreamFormat.FETCH_IO_SIZE from the configuration and casts it to an int via MathUtils.checkedDownCast. If the resulting fetchSize is zero or negative, it throws IllegalConfigurationException. FETCH_IO_SIZE is a MemorySize option that controls the I/O buffer size for reading streams; a value of 0 bytes or any value that truncates to <= 0 is invalid.

Source

Thrown at flink-connectors/flink-connector-files/src/main/java/org/apache/flink/connector/file/src/impl/StreamFormatAdapter.java:162

        return streamFormat.isSplittable();
    }

    @Override
    public TypeInformation<T> getProducedType() {
        return streamFormat.getProducedType();
    }

    private static TrackingFsDataInputStream openStream(
            final Path file, final Configuration config, final long seekPosition)
            throws IOException {

        final FileSystem fs = file.getFileSystem();
        final long fileLength = fs.getFileStatus(file).getLen();

        final int fetchSize =
                MathUtils.checkedDownCast(config.get(StreamFormat.FETCH_IO_SIZE).getBytes());
        if (fetchSize <= 0) {
            throw new IllegalConfigurationException(
                    String.format(
                            "The fetch size (%s) must be > 0, but is %d",
                            StreamFormat.FETCH_IO_SIZE.key(), fetchSize));
        }

        final InflaterInputStreamFactory<?> deCompressor =
                StandardDeCompressors.getDecompressorForFileName(file.getPath());

        final FSDataInputStream inStream = fs.open(file);
        return doWithCleanupOnException(
                inStream,
                () -> {
                    final FSDataInputStream in =
                            deCompressor == null
                                    ? inStream
                                    : new InputStreamFSInputWrapper(deCompressor.create(inStream));
                    in.seek(seekPosition);
                    return new TrackingFsDataInputStream(in, fileLength, fetchSize);

View on GitHub (pinned to 2f3c205e92)

Solutions

Set StreamFormat.FETCH_IO_SIZE to a positive value, e.g. '1mb' or larger. The default is typically sufficient; remove the override if unsure.
If configuring programmatically, ensure MemorySize.ofBytes(N) where N > 0.
Search configuration files and table DDL options for any 'fetch-io-size' or equivalent key set to 0.

Example fix

// before
ConfigOption<MemorySize> fetchSize = ...;
config.set(StreamFormat.FETCH_IO_SIZE, MemorySize.parse("0"));

// after
config.set(StreamFormat.FETCH_IO_SIZE, MemorySize.parse("1mb"));
// or simply omit the option to use the default

Defensive patterns

Strategy: validation

Validate before calling

// Validate FETCH_IO_SIZE before starting the source
MemorySize fetchSize = config.get(StreamFormat.FETCH_IO_SIZE);
if (fetchSize.getBytes() <= 0) {
    throw new IllegalArgumentException(
        "StreamFormat.FETCH_IO_SIZE must be > 0, got: " + fetchSize);
}

Prevention

Never set StreamFormat.FETCH_IO_SIZE to 0 or a negative value.
Use the default value unless there is a specific reason to change it.
Validate MemorySize options in configuration builders before job submission.

When it happens

Trigger: The configuration option StreamFormat.FETCH_IO_SIZE is set to 0 bytes, a negative value, or a value that overflows when cast to int. The check is `fetchSize <= 0` after checkedDownCast, so even a very large value that doesn't overflow but is somehow 0 after cast would trigger it (though the realistic trigger is an explicit 0-byte configuration).

Common situations: Explicitly setting the fetch I/O size to 0 bytes in table or pipeline configuration. Misconfiguration where a MemorySize option is set to '0' or '0b'. Copy-paste error in config templates.

Related errors

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