apache/flink · error · IllegalArgumentException

Number of line samples must not be negative.

Error message

Number of line samples must not be negative.

What it means

DelimitedInputFormat uses numLineSamples to decide how many records to sample when computing input statistics for split sizing. 0 means 'disable sampling' (a valid value); negative is invalid. setNumLineSamples rejects negatives to distinguish 'disabled' (0) from 'misconfigured'.

Source

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

    public int getBufferSize() {
        return bufferSize;
    }

    public void setBufferSize(int bufferSize) {
        if (bufferSize < 2) {
            throw new IllegalArgumentException("Buffer size must be at least 2.");
        }

        this.bufferSize = bufferSize;
    }

    public int getNumLineSamples() {
        return numLineSamples;
    }

    public void setNumLineSamples(int numLineSamples) {
        if (numLineSamples < 0) {
            throw new IllegalArgumentException("Number of line samples must not be negative.");
        }
        this.numLineSamples = numLineSamples;
    }

    // --------------------------------------------------------------------------------------------
    //  User-defined behavior
    // --------------------------------------------------------------------------------------------

    /**
     * This function parses the given byte array which represents a serialized record. The function
     * returns a valid record or throws an IOException.
     *
     * @param reuse An optionally reusable object.
     * @param bytes Binary data of serialized records.
     * @param offset The offset where to start to read the record data.
     * @param numBytes The number of bytes that can be read starting at the offset position.
     * @return Returns the read record if it was successfully deserialized.
     * @throws IOException if the record could not be read.

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Pass 0 to disable sampling, or a positive count (e.g. format.setNumLineSamples(10)).
2. Coerce negative inputs to 0 (disable) before calling setNumLineSamples.
3. Use the default (NUM_SAMPLES_UNDEFINED is resolved at getStatistics time, not here).

Example fix

// before
format.setNumLineSamples(sampleCount); // sampleCount == -1 -> throws

// after
int n = sampleCount >= 0 ? sampleCount : 0;
format.setNumLineSamples(n);

int n = configuredNumLineSamples >= 0 ? configuredNumLineSamples : 0;
format.setNumLineSamples(n);

When it happens

Trigger: Calling format.setNumLineSamples(-1) or any negative integer.

Common situations: Passing -1 intending 'unlimited' (the format does not support that); computing the sample count from a subtraction that underflows; reading the value from a config that uses -1 as 'undefined'.

Related errors

• Delimiter must not be null
• Line length limit must be at least 1.
• Buffer size must be at least 2.
• Buffer size must be greater than length of delimiter.
• The block size parameter must be set and larger than 0.

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