apache/kafka · error · UnsupportedVersionException

The node does not support {apiKey} with version in range [{o

Error message

The node does not support {apiKey} with version in range [{oldestAllowedVersion},{latestAllowedVersion}]. The supported range is [{minVersion},{maxVersion}].

What it means

Thrown by NodeApiVersions.latestUsableVersion(ApiKeys, oldestAllowedVersion, latestAllowedVersion) when the broker does advertise the API but the requested version range does not intersect the broker's supported [minVersion, maxVersion]. It is an UnsupportedVersionException carrying the exact supported range so the caller can reconcile. The client computes the intersection via ApiVersionsResponse.intersect; an empty intersection means even the highest mutually-known version is outside the caller's allowed band.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/NodeApiVersions.java:162

    }

    /**
     * Get the latest version supported by the broker within an allowed range of versions
     */
    public short latestUsableVersion(ApiKeys apiKey, short oldestAllowedVersion, short latestAllowedVersion) {
        if (!supportedVersions.containsKey(apiKey))
            throw new UnsupportedVersionException("The node does not support " + apiKey);
        ApiVersion supportedVersion = supportedVersions.get(apiKey);
        Optional<ApiVersion> intersectVersion = ApiVersionsResponse.intersect(supportedVersion,
            new ApiVersion()
                .setApiKey(apiKey.id)
                .setMinVersion(oldestAllowedVersion)
                .setMaxVersion(latestAllowedVersion));

        if (intersectVersion.isPresent())
            return intersectVersion.get().maxVersion();
        else
            throw new UnsupportedVersionException("The node does not support " + apiKey +
                " with version in range [" + oldestAllowedVersion + "," + latestAllowedVersion + "]. The supported" +
                " range is [" + supportedVersion.minVersion() + "," + supportedVersion.maxVersion() + "].");
    }

    /**
     * Convert the object to a string with no linebreaks.<p/>
     * <p>
     * This toString method is relatively expensive, so avoid calling it unless debug logging is turned on.
     */
    @Override
    public String toString() {
        return toString(false);
    }

    /**
     * Convert the object to a string.
     *
     * @param lineBreaks True if we should add a linebreak after each api.

View on GitHub (pinned to c31c9215e1)

Solutions

Align client and broker versions so the requested version band overlaps the supported range shown in the message.
If passing explicit oldestAllowedVersion/latestAllowedVersion, widen or lower the band to intersect [minVersion,maxVersion] from the error text.
Upgrade the broker so its maxVersion covers the band you need, or downgrade the client to use lower protocol versions.
Use the no-arg latestUsableVersion(apiKey) overload to let the client pick the highest mutually supported version automatically.

Example fix

// before - pinning a band the broker cannot satisfy
short v = nodeApiVersions.latestUsableVersion(
    ApiKeys.FETCH, (short) 5, (short) 7);

// after - let the client negotiate, or use a band inside [minVersion,maxVersion]
short v = nodeApiVersions.latestUsableVersion(ApiKeys.FETCH);
// or: pass bounds within the broker-supported range, e.g. [2,3]

Defensive patterns

Strategy: validation

Validate before calling

// Verify the requested version range overlaps the broker's supported range BEFORE
// calling latestUsableVersion(apiKey, oldest, latest).
ApiVersion supported = nodeApiVersions.supportedVersions().get(apiKey);
if (supported == null) {
    // handled by errorIndex 30
    return;
}
boolean overlaps =
    Math.max(supported.minVersion(), oldestAllowedVersion) <=
    Math.min(supported.maxVersion(), latestAllowedVersion);
if (!overlaps) {
    log.warn("No overlap between requested [{},{}} and supported [{},{}] for {}",
        oldestAllowedVersion, latestAllowedVersion,
        supported.minVersion(), supported.maxVersion(), apiKey);
    return;
}
short v = nodeApiVersions.latestUsableVersion(apiKey, oldestAllowedVersion, latestAllowedVersion);

Try / catch

try {
    short v = nodeApiVersions.latestUsableVersion(apiKey, oldestAllowedVersion, latestAllowedVersion);
} catch (org.apache.kafka.common.errors.UnsupportedVersionException e) {
    // Message prints both the requested and the supported range; use it to pick a
    // new oldestAllowedVersion/latestAllowedVersion inside the supported window.
    log.warn("Version-range mismatch for {}: {}", apiKey, e.getMessage());
}

Prevention

When passing an explicit version range, widen oldestAllowedVersion down to apiKey.oldestVersion() unless you have a hard floor.
Compute the intersection client-side from NodeApiVersions.supportedVersions() before calling latestUsableVersion(..., oldest, latest).
Avoid pinning latestAllowedVersion below the broker's minVersion; that is the most common cause of a zero-length intersection.
Treat UnsupportedVersionException as a signal to recompute the range from the broker's advertised min/max, not as a transient retryable fault.

When it happens

Trigger: Caller restricts oldestAllowedVersion/latestAllowedVersion to a band the broker cannot satisfy (e.g. asking for API versions >= 5 when broker maxes at 3, or asking for a band below the broker's minimum). Reachable from Admin/Client internals that pin API versions, or from user code that calls latestUsableVersion with explicit bounds. Also surfaces during a downgrade where the client insists on a newer protocol version than the broker supports.

Common situations: Broker downgrade without client downgrade (client pins a version the old broker no longer speaks); explicit version negotiation in tests or custom clients that pass wrong bounds; mixed-version cluster where a newer API range is requested from an older node; client uses a feature flag that requires a specific protocol version not yet rolled out.

Related errors

The node does not support {apiKey}

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