apache/kafka · error · UnsupportedVersionException

The node does not support

Error message

The node does not support {apiKey}

What it means

Thrown by NodeApiVersions.latestUsableVersion() when the broker's reported API versions map does not contain an entry for the given ApiKeys. This means the broker entirely lacks support for that API key, so no version intersection is possible.

Solutions

1. Upgrade the broker to a version that supports the required API key.
2. Downgrade the client to match the broker's supported API surface.
3. Check ApiVersionsResponse from the broker to confirm which API keys are advertised.
4. For optional features, gate the code path on broker version compatibility.

NodeApiVersions versions = ...;
if (!versions.supportedVersions.containsKey(apiKey)) {
    throw new UnsupportedVersionException("Broker lacks API " + apiKey);
}

boolean brokerSupportsApi(NodeApiVersions v, ApiKeys key) {
    return v.supportedVersions().containsKey(key);
}

try {
    short v = nodeApiVersions.latestUsableVersion(apiKey);
} catch (UnsupportedVersionException e) {
    // broker does not support this API at all
}

When it happens

Trigger: Calling latestUsableVersion(apiKey, ...) where supportedVersions (from the broker's ApiVersionsResponse) has no entry for apiKey. The broker did not advertise this API at all.

Common situations: Client/broker version skew where the client uses a newer API key not yet known to an older broker (e.g. a KRaft-era API against a very old broker), or a broker that intentionally omits certain APIs.

Related errors

• The node does not support

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

Appendix: source

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

        this.finalizedFeatures = new HashMap<>();
        for (ApiVersionsResponseData.FinalizedFeatureKey finalizedFeature : nodeFinalizedFeatures) {
            this.finalizedFeatures.put(finalizedFeature.name(), finalizedFeature.maxVersionLevel());
        }
    }

    /**
     * Return the most recent version supported by both the node and the local software.
     */
    public short latestUsableVersion(ApiKeys apiKey) {
        return latestUsableVersion(apiKey, apiKey.oldestVersion(), apiKey.latestVersion());
    }

    /**
     * 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>

View on GitHub (pinned to 996fb4585a)