apache/kafka · error · IllegalArgumentException

Expected 0 <= minVersion <= maxVersion but received minVersi

Error message

Expected 0 <= minVersion <= maxVersion but received minVersion:%d, maxVersion:%d.

What it means

Thrown by the SupportedVersionRange constructor when minVersion or maxVersion is negative, or when maxVersion is less than minVersion. SupportedVersionRange models the [min,max] feature-version range a broker advertises; the invariant 0 <= minVersion <= maxVersion is fundamental and any violation indicates corrupt or malformed feature metadata. This is a hard precondition check inside the admin/feature-metadata layer.

Source

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

 */
@InterfaceAudience.Public
public class SupportedVersionRange {
    private final short minVersion;

    private final short maxVersion;

    /**
     * Raises an exception unless the following conditions are met:
     *  0 <= minVersion <= maxVersion.
     *
     * @param minVersion           The minimum version value.
     * @param maxVersion           The maximum version value.
     *
     * @throws IllegalArgumentException   Raised when the condition described above is not met.
     */
    public SupportedVersionRange(final short minVersion, final short maxVersion) {
        if (minVersion < 0 || maxVersion < 0 || maxVersion < minVersion) {
            throw new IllegalArgumentException(
                String.format(
                    "Expected 0 <= minVersion <= maxVersion but received minVersion:%d, maxVersion:%d.",
                    minVersion,
                    maxVersion));
        }
        this.minVersion = minVersion;
        this.maxVersion = maxVersion;
    }

    public short minVersion() {
        return minVersion;
    }

    public short maxVersion() {
        return maxVersion;
    }

    @Override

View on GitHub (pinned to c31c9215e1)

Solutions

1. Verify the broker version is compliant with feature negotiation (KIP-554+) and is a genuine Kafka broker, not a proxy stripping feature data.
2. If constructing SupportedVersionRange directly, ensure 0 <= minVersion and minVersion <= maxVersion before calling the constructor.
3. Upgrade brokers and clients to the same Kafka version to avoid malformed feature-range responses from older brokers.
4. Inspect the broker-side FinalizedFeatureRange / SupportedFeatureRange emission for corruption.

Example fix

// before
new SupportedVersionRange((short) 5, (short) 2); // max < min -> throws

// after
new SupportedVersionRange((short) 2, (short) 5);

// Validate version bounds before constructing SupportedVersionRange:
short minVersion = ..., maxVersion = ...;
if (minVersion < 0 || maxVersion < 0 || maxVersion < minVersion) {
    throw new IllegalArgumentException("Refusing to build SupportedVersionRange with min=" + minVersion + ", max=" + maxVersion);
}
new SupportedVersionRange(minVersion, maxVersion);

static boolean isValidVersionRange(short minVersion, short maxVersion) {
    return minVersion >= 0 && maxVersion >= 0 && maxVersion >= minVersion;
}

try {
    new SupportedVersionRange(minVersion, maxVersion);
} catch (IllegalArgumentException e) {
    // clamp or reject; this usually indicates corrupt metadata from the broker
    throw new RuntimeException("Unsupported feature version range received", e);
}

When it happens

Trigger: Constructing SupportedVersionRange(minVersion, maxVersion) directly with bad arguments, or—more commonly—parsing broker-sent FinalizedFeatureRange or SupportedFeatureRange data where the broker advertised an inverted or negative range. Reached during ApiVersionsResponse / finalized feature handling.

Common situations: A misbehaving or non-compliant broker (older pre-KIP-554 broker, a proxy, or a mock/stub interceptor) returning feature ranges with negative or swapped min/max; manual construction of feature metadata in tests with swapped arguments; corrupt in-memory state after a partial serialization failure.

Related errors

• Member {member} was not included in the original request
• Unknown topology description status id: {id}
• Topic partitions to assign to cannot have null or empty topi
• RebalanceListener cannot be null
• Topic pattern to subscribe to cannot be null

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