apache/flink · error · IllegalArgumentException

The size of produced records must be positive.

Error message

The size of produced records must be positive.

What it means

Thrown by CompilerHints.setAvgOutputRecordSize(float) when the provided value is <= 0. Unlike outputSize and outputCardinality which allow zero (an empty result is valid), the average record size must be strictly positive because a zero or negative record size is physically meaningless. The default is -1.0f (meaning 'unset'). This is an IllegalArgumentException.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/operators/CompilerHints.java:81

        return this.outputCardinality;
    }

    public void setOutputCardinality(long outputCardinality) {
        if (outputCardinality < 0) {
            throw new IllegalArgumentException(
                    "The output cardinality cannot be smaller than zero.");
        }

        this.outputCardinality = outputCardinality;
    }

    public float getAvgOutputRecordSize() {
        return this.avgOutputRecordSize;
    }

    public void setAvgOutputRecordSize(float avgOutputRecordSize) {
        if (avgOutputRecordSize <= 0) {
            throw new IllegalArgumentException("The size of produced records must be positive.");
        }

        this.avgOutputRecordSize = avgOutputRecordSize;
    }

    public float getFilterFactor() {
        return filterFactor;
    }

    public void setFilterFactor(float filterFactor) {
        if (filterFactor < 0) {
            throw new IllegalArgumentException("The filter factor cannot be smaller than zero.");
        }

        this.filterFactor = filterFactor;
    }

    // --------------------------------------------------------------------------------------------

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Ensure the average record size is strictly > 0 before calling setAvgOutputRecordSize().
2. Guard division: if computing avgOutputRecordSize = outputSize / cardinality, check that cardinality > 0 and the result > 0 before setting.
3. If the value is unknown or zero, omit the call (the default -1.0f signals 'unset').

Example fix

// before
float avgSize = (float) totalBytes / recordCount;  // recordCount could be 0
hints.setAvgOutputRecordSize(avgSize);
// after
if (recordCount > 0) {
    float avgSize = (float) totalBytes / recordCount;
    if (avgSize > 0) {
        hints.setAvgOutputRecordSize(avgSize);
    }
}

// Guard against non-positive average record size before setting
if (avgOutputRecordSize <= 0) {
    throw new IllegalArgumentException("avgOutputRecordSize must be > 0, got: " + avgOutputRecordSize);
}
hints.setAvgOutputRecordSize(avgOutputRecordSize);
// Or omit the call if unknown (default -1.0f means 'unset')

When it happens

Trigger: Calling setAvgOutputRecordSize() with 0 or a negative float. This can happen if the value is computed by dividing total size by cardinality where cardinality is 0 (producing 0 or NaN), or from an uninitialized value of 0.0f.

Common situations: An @Internal API used in optimizer internals. The average record size is often computed as outputSize / outputCardinality; if cardinality is 0 this yields 0.0 or Infinity, and passing that result to setAvgOutputRecordSize() triggers the exception. Also triggered by passing a computed hint where the source data has zero records.

Related errors

• The output size cannot be smaller than zero.
• The output cardinality cannot be smaller than zero.
• The filter factor cannot be smaller than zero.
• Return type {keyType} of KeySelector {keyExtractor.getClass(
• Custom partitioners can only be used with keys that have one

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