apache/kafka · error · IllegalArgumentException

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

Q: What causes "Expected minVersionLevel >= 0, maxVersionLevel >= 0 and maxVersionLevel >= minVersionLevel, but received minVersionLevel: %d, maxVersionLevel: %d" in apache/kafka?

Ensure 0 <= min <= max before constructing; pass min first, then max.

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 minVersionLevel or maxVersionLevel is negative, or when max is less than min. These invariants define a legal finalized feature version range. Note the Javadoc claims the floor is 1 but the code actually enforces >= 0, so zero is currently accepted.

Solutions

Ensure 0 <= min <= max before constructing; pass min first, then max.
If the values come from the wire, treat the exception as protocol corruption and surface it rather than retrying the same payload.
Add a unit test asserting min <= max for every range your code builds.

Example fix

// before
new FinalizedVersionRange(maxLevel, minLevel); // swapped

// after
new FinalizedVersionRange(minLevel, maxLevel);

Defensive patterns

Strategy: validation

Validate before calling

if (min < 0 || max < 0 || max < min) {
    throw new IllegalArgumentException("Illegal range min=" + min + " max=" + max);
}
new FinalizedVersionRange(min, max);

Type guard

static boolean isLegalVersionRange(short min, short max) {
    return min >= 0 && max >= 0 && max >= min;
}

Prevention

Always pass min first, then max.
Assert min <= max in unit tests for every range your code builds.

When it happens

Trigger: Constructing new FinalizedVersionRange(min, max) with a negative argument, or with max < min (e.g. new FinalizedVersionRange((short) 5, (short) 3)). Building a range from deserialized protocol data where the broker sent inconsistent values.

Common situations: Wrong argument order (passing max first); off-by-one in version arithmetic; deserialization of corrupt protocol payloads from a buggy or malicious broker.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/961a7361efcb0f8a. Report an issue: GitHub.

Appendix: 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 996fb4585a)