{"record":{"id":"93fce89a46cb1397","repo":"apache/kafka","slug":"the-node-does-not-support-apikey-with-version-in","errorCode":null,"errorMessage":"The node does not support {apiKey} with version in range [{oldestAllowedVersion},{latestAllowedVersion}]. The supported range is [{supportedVersion.minVersion()},{supportedVersion.maxVersion()}].","messagePattern":"The node does not support (.+?) with version in range \\[(.+?),(.+?)\\]\\. The supported range is \\[(.+?),(.+?)\\]\\.","errorType":"exception","errorClass":"UnsupportedVersionException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/NodeApiVersions.java","lineNumber":162,"sourceCode":"    }\n\n    /**\n     * Get the latest version supported by the broker within an allowed range of versions\n     */\n    public short latestUsableVersion(ApiKeys apiKey, short oldestAllowedVersion, short latestAllowedVersion) {\n        if (!supportedVersions.containsKey(apiKey))\n            throw new UnsupportedVersionException(\"The node does not support \" + apiKey);\n        ApiVersion supportedVersion = supportedVersions.get(apiKey);\n        Optional<ApiVersion> intersectVersion = ApiVersionsResponse.intersect(supportedVersion,\n            new ApiVersion()\n                .setApiKey(apiKey.id)\n                .setMinVersion(oldestAllowedVersion)\n                .setMaxVersion(latestAllowedVersion));\n\n        if (intersectVersion.isPresent())\n            return intersectVersion.get().maxVersion();\n        else\n            throw new UnsupportedVersionException(\"The node does not support \" + apiKey +\n                \" with version in range [\" + oldestAllowedVersion + \",\" + latestAllowedVersion + \"]. The supported\" +\n                \" range is [\" + supportedVersion.minVersion() + \",\" + supportedVersion.maxVersion() + \"].\");\n    }\n\n    /**\n     * Convert the object to a string with no linebreaks.<p/>\n     * <p>\n     * This toString method is relatively expensive, so avoid calling it unless debug logging is turned on.\n     */\n    @Override\n    public String toString() {\n        return toString(false);\n    }\n\n    /**\n     * Convert the object to a string.\n     *\n     * @param lineBreaks True if we should add a linebreak after each api.","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/NodeApiVersions.java#L144-L180","documentation":"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.","triggerScenarios":"supportedVersions contains the apiKey, but ApiVersionsResponse.intersect(...) returns Optional.empty() because the broker's version range does not overlap with [oldestAllowedVersion, latestAllowedVersion].","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"ApiVersion brokerRange = nodeApiVersions.supportedVersions.get(apiKey);\nif (brokerRange == null\n    || brokerRange.maxVersion() < oldestAllowedVersion\n    || brokerRange.minVersion() > latestAllowedVersion) {\n    throw new UnsupportedVersionException(\"No overlapping version for \" + apiKey);\n}","typeGuard":"boolean versionsOverlap(ApiVersion broker, short minReq, short maxReq) {\n    return broker != null\n        && broker.minVersion() <= maxReq\n        && broker.maxVersion() >= minReq;\n}","tryCatchPattern":"try {\n    short v = nodeApiVersions.latestUsableVersion(apiKey, minReq, maxReq);\n} catch (UnsupportedVersionException e) {\n    // broker range does not overlap required range\n}","preventionTips":["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."],"tags":["versioning","compatibility","api"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}