{"id":"789b34f8210da872","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 [{minVersion},{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/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/NodeApiVersions.java#L144-L180","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before - pinning a band the broker cannot satisfy\nshort v = nodeApiVersions.latestUsableVersion(\n    ApiKeys.FETCH, (short) 5, (short) 7);\n\n// after - let the client negotiate, or use a band inside [minVersion,maxVersion]\nshort v = nodeApiVersions.latestUsableVersion(ApiKeys.FETCH);\n// or: pass bounds within the broker-supported range, e.g. [2,3]","handlingStrategy":"validation","validationCode":"// Verify the requested version range overlaps the broker's supported range BEFORE\n// calling latestUsableVersion(apiKey, oldest, latest).\nApiVersion supported = nodeApiVersions.supportedVersions().get(apiKey);\nif (supported == null) {\n    // handled by errorIndex 30\n    return;\n}\nboolean overlaps =\n    Math.max(supported.minVersion(), oldestAllowedVersion) <=\n    Math.min(supported.maxVersion(), latestAllowedVersion);\nif (!overlaps) {\n    log.warn(\"No overlap between requested [{},{}} and supported [{},{}] for {}\",\n        oldestAllowedVersion, latestAllowedVersion,\n        supported.minVersion(), supported.maxVersion(), apiKey);\n    return;\n}\nshort v = nodeApiVersions.latestUsableVersion(apiKey, oldestAllowedVersion, latestAllowedVersion);","typeGuard":null,"tryCatchPattern":"try {\n    short v = nodeApiVersions.latestUsableVersion(apiKey, oldestAllowedVersion, latestAllowedVersion);\n} catch (org.apache.kafka.common.errors.UnsupportedVersionException e) {\n    // Message prints both the requested and the supported range; use it to pick a\n    // new oldestAllowedVersion/latestAllowedVersion inside the supported window.\n    log.warn(\"Version-range mismatch for {}: {}\", apiKey, e.getMessage());\n}","preventionTips":["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."],"tags":["api-versioning","broker-compatibility","client-server","unsupported-version","version-negotiation"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}