apache/kafka · error · UnsupportedVersionException

The node does not support {apiKey}

Error message

The node does not support {apiKey}

What it means

Thrown by NodeApiVersions.latestUsableVersion when the broker's ApiVersions response did not advertise support for the requested ApiKeys at all. The client maintains a per-node map of supported API versions (populated from the handshake response); a lookup against an absent key means the remote broker is older than the API itself, or the API is optional and disabled on that node. This is an UnsupportedVersionException, signalling a fundamental client/broker capability mismatch for that single API.

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 c31c9215e1)

Solutions

1. Upgrade the broker to a version that supports the listed apiKey (check the broker's effective ApiVersions via kafka-features or Admin.describeFeatures).
2. Downgrade the client to match the broker's supported API set.
3. If in a rolling upgrade, wait until all brokers are upgraded and target only upgraded nodes.
4. Verify the node role (controller vs broker) matches the API you are calling.

Example fix

// before - new client calling KRaft-only API against old broker
Admin admin = Admin.create(props);
admin.describeLogDirs(...).get();

// after - gate on broker capability before calling
NodeApiVersions v = admin.describeCluster().nodes().get()
    .stream().findFirst().get().hasApiVersions();
// or upgrade brokers to >= 3.x where the API exists

// Inspect the broker-advertised ApiVersions before picking a version.
// `nodeApiVersions` comes from an ApiVersionsResponse (e.g. via AdminClient internals
// or connection.node(...).apiVersions()).
if (nodeApiVersions == null || !nodeApiVersions.supportedVersions().containsKey(apiKey)) {
    // broker does not advertise this API key at all
    log.warn("Broker does not support API {}; disabling dependent feature", apiKey);
    return; // or fall back to an older code path
}
short v = nodeApiVersions.latestUsableVersion(apiKey);

try {
    short v = nodeApiVersions.latestUsableVersion(apiKey);
} catch (org.apache.kafka.common.errors.UnsupportedVersionException e) {
    // Broker is too old / does not implement this API key.
    // Degrade to a code path that does not require `apiKey`.
    log.warn("Unsupported API {} on broker: {}", apiKey, e.getMessage());
}

When it happens

Trigger: Calling latestUsableVersion(apiKey) where the broker returned no entry for apiKey in its ApiVersionsResponse. Happens when a newer client uses an ApiKeys introduced after the broker version (e.g. KRaft admin APIs against a pre-KRaft broker), or when a node filtered out an API via configuration. Also reachable through any internal code path that negotiates an API version per node (NetworkClient, Admin handshake).

Common situations: Client jar version is newer than the broker (e.g. 3.x client talking to 2.x broker); broker is in mixed-version cluster during rolling upgrade and the targeted node has not been upgraded yet; an API is gated behind a broker config that is disabled on the node; pointing a tool at a broker that does not host the relevant controller/coordinator role.

Related errors

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

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