apache/kafka · error · IllegalArgumentException

Expected minVersionLevel >= 0, maxVersionLevel >= 0 and maxV

Error message

Expected minVersionLevel >= 0, maxVersionLevel >= 0 and maxVersionLevel >= minVersionLevel, but received minVersionLevel: %d, maxVersionLevel: %d

What it means

Thrown by the FinalizedVersionRange constructor when the supplied minVersionLevel/maxVersionLevel pair fails any of: minVersionLevel >= 0, maxVersionLevel >= 0, or maxVersionLevel >= minVersionLevel. This invariant defines a valid non-negative, ordered version range for a finalized feature across the cluster. Note the Javadoc mentions >= 1 historically but the code enforces >= 0; either way the message names the exact failed condition.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/FinalizedVersionRange.java:44

 */
@InterfaceAudience.Public
public class FinalizedVersionRange {
    private final short minVersionLevel;

    private final short maxVersionLevel;

    /**
     * Raises an exception unless the following condition is met:
     * {@code minVersionLevel >= 1} and {@code maxVersionLevel >= 1} and {@code maxVersionLevel >= minVersionLevel}.
     *
     * @param minVersionLevel   The minimum version level value.
     * @param maxVersionLevel   The maximum version level value.
     *
     * @throws IllegalArgumentException   Raised when the condition described above is not met.
     */
    public FinalizedVersionRange(final short minVersionLevel, final short maxVersionLevel) {
        if (minVersionLevel < 0 || maxVersionLevel < 0 || maxVersionLevel < minVersionLevel) {
            throw new IllegalArgumentException(
                String.format(
                    "Expected minVersionLevel >= 0, maxVersionLevel >= 0 and" +
                    " maxVersionLevel >= minVersionLevel, but received" +
                    " minVersionLevel: %d, maxVersionLevel: %d", minVersionLevel, maxVersionLevel));
        }
        this.minVersionLevel = minVersionLevel;
        this.maxVersionLevel = maxVersionLevel;
    }

    public short minVersionLevel() {
        return minVersionLevel;
    }

    public short maxVersionLevel() {
        return maxVersionLevel;
    }

    @Override

View on GitHub (pinned to c31c9215e1)

Solutions

Ensure both levels are >= 0 (typically >= 1 for real features) and that max >= min before constructing.
Swap the arguments if you accidentally passed them in the wrong order (the message tells you which is which).
Validate and clamp external input before constructing the range.
Add a guard clause or precondition (e.g. checkArgument) upstream so the error is caught earlier.

Example fix

// before - args swapped / out of range
new FinalizedVersionRange((short) 5, (short) 2);
new FinalizedVersionRange((short) -1, (short) 3);

// after - valid non-negative ordered range
new FinalizedVersionRange((short) 2, (short) 5);

Defensive patterns

Strategy: validation

Validate before calling

// FinalizedVersionRange requires min>=0, max>=0, max>=min.
short minVersionLevel = ...;
short maxVersionLevel = ...;
if (minVersionLevel < 0 || maxVersionLevel < 0 || maxVersionLevel < minVersionLevel) {
    throw new IllegalArgumentException(String.format(
        "Invalid FinalizedVersionRange: min=%d max=%d", minVersionLevel, maxVersionLevel));
}
FinalizedVersionRange range = new FinalizedVersionRange(minVersionLevel, maxVersionLevel);

Type guard

// Predicate narrowing a (short, short) pair to a range-safe value.
static boolean isValidVersionRange(short min, short max) {
    return min >= 0 && max >= 0 && max >= min;
}

Try / catch

try {
    FinalizedVersionRange range = new FinalizedVersionRange(minVersionLevel, maxVersionLevel);
} catch (IllegalArgumentException e) {
    // Inverted or negative range. Swap if inverted, clamp to 0 if negative, or reject.
    log.error("Invalid FinalizedVersionRange({}, {}): {}",
        minVersionLevel, maxVersionLevel, e.getMessage());
}

Prevention

Validate min/max ordering at the config boundary before constructing FinalizedVersionRange.
Wrap construction in a factory that enforces min>=0, max>=0, max>=min in one place.
When reading levels from user input, parse to int first, range-check, then narrow to short.
Unit-test boundary cases (0,0), (1,1), (1, Short.MAX_VALUE), and the inverted (2,1).

When it happens

Trigger: Constructing new FinalizedVersionRange(min, max) with a negative min or max, or with min > max. Reached from code that builds a finalized feature range from computed values, external config, or deserialized controller data without prior validation.

Common situations: Caller computes min/max from subtractions that underflow; swap of min and max arguments; external config feeding negative or inverted numbers; tests using placeholder literals; corrupted metadata being reconstructed client-side.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/961a7361efcb0f8a.json. Report an issue: GitHub.