apache/kafka · error · UnsupportedVersionException

The node does not support

Error message

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

What it means

Thrown by NodeApiVersions.latestUsableVersion() when the broker DOES support the given ApiKeys, but the intersection of the broker's supported version range [minVersion, maxVersion] and the caller's allowed range [oldestAllowedVersion, latestAllowedVersion] is empty. The message reports both the requested range and the broker's supported range.

Solutions

Upgrade the broker so its API version range overlaps the client's required range.
Lower the client's required minimum version if the feature is optional.
Verify the feature's documented minimum broker version and ensure compliance.
Inspect NodeApiVersions output to see the broker's actual supported range for the API.

Defensive patterns

Strategy: validation

Validate before calling

ApiVersion brokerRange = nodeApiVersions.supportedVersions.get(apiKey);
if (brokerRange == null
    || brokerRange.maxVersion() < oldestAllowedVersion
    || brokerRange.minVersion() > latestAllowedVersion) {
    throw new UnsupportedVersionException("No overlapping version for " + apiKey);
}

Type guard

boolean versionsOverlap(ApiVersion broker, short minReq, short maxReq) {
    return broker != null
        && broker.minVersion() <= maxReq
        && broker.maxVersion() >= minReq;
}

Try / catch

try {
    short v = nodeApiVersions.latestUsableVersion(apiKey, minReq, maxReq);
} catch (UnsupportedVersionException e) {
    // broker range does not overlap required range
}

Prevention

Inspect NodeApiVersions to learn each broker's actual version range.
Pin the minimum broker version in deployment docs per feature.
Gate feature usage on a version-overlap check, not just presence.

When it happens

Trigger: supportedVersions contains the apiKey, but ApiVersionsResponse.intersect(...) returns Optional.empty() because the broker's version range does not overlap with [oldestAllowedVersion, latestAllowedVersion].

Common situations: Client requires a minimum API version higher than the broker's max (e.g. needs v3 but broker only supports v0-v2), or the client's allowed range is entirely below the broker's minimum. Common after enabling a feature that needs a newer API version on an older broker.

Related errors

The node does not support

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

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