{"id":"11bba96dd50b5024","repo":"apache/kafka","slug":"the-node-does-not-support-apikey","errorCode":null,"errorMessage":"The node does not support {apiKey}","messagePattern":"The node does not support (.+?)","errorType":"exception","errorClass":"UnsupportedVersionException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/NodeApiVersions.java","lineNumber":151,"sourceCode":"        this.finalizedFeatures = new HashMap<>();\n        for (ApiVersionsResponseData.FinalizedFeatureKey finalizedFeature : nodeFinalizedFeatures) {\n            this.finalizedFeatures.put(finalizedFeature.name(), finalizedFeature.maxVersionLevel());\n        }\n    }\n\n    /**\n     * Return the most recent version supported by both the node and the local software.\n     */\n    public short latestUsableVersion(ApiKeys apiKey) {\n        return latestUsableVersion(apiKey, apiKey.oldestVersion(), apiKey.latestVersion());\n    }\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>","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/NodeApiVersions.java#L133-L169","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Upgrade the broker to a version that supports the listed apiKey (check the broker's effective ApiVersions via kafka-features or Admin.describeFeatures).","Downgrade the client to match the broker's supported API set.","If in a rolling upgrade, wait until all brokers are upgraded and target only upgraded nodes.","Verify the node role (controller vs broker) matches the API you are calling."],"exampleFix":"// before - new client calling KRaft-only API against old broker\nAdmin admin = Admin.create(props);\nadmin.describeLogDirs(...).get();\n\n// after - gate on broker capability before calling\nNodeApiVersions v = admin.describeCluster().nodes().get()\n    .stream().findFirst().get().hasApiVersions();\n// or upgrade brokers to >= 3.x where the API exists","handlingStrategy":"validation","validationCode":"// Inspect the broker-advertised ApiVersions before picking a version.\n// `nodeApiVersions` comes from an ApiVersionsResponse (e.g. via AdminClient internals\n// or connection.node(...).apiVersions()).\nif (nodeApiVersions == null || !nodeApiVersions.supportedVersions().containsKey(apiKey)) {\n    // broker does not advertise this API key at all\n    log.warn(\"Broker does not support API {}; disabling dependent feature\", apiKey);\n    return; // or fall back to an older code path\n}\nshort v = nodeApiVersions.latestUsableVersion(apiKey);","typeGuard":null,"tryCatchPattern":"try {\n    short v = nodeApiVersions.latestUsableVersion(apiKey);\n} catch (org.apache.kafka.common.errors.UnsupportedVersionException e) {\n    // Broker is too old / does not implement this API key.\n    // Degrade to a code path that does not require `apiKey`.\n    log.warn(\"Unsupported API {} on broker: {}\", apiKey, e.getMessage());\n}","preventionTips":["Cache NodeApiVersions per broker and consult supportedVersions() before issuing requests that depend on a specific ApiKeys entry.","After first connecting to a broker, log the advertised ApiKeys so unsupported APIs surface during integration rather than at runtime.","Prefer the high-level Admin/KafkaProducer/KafkaConsumer APIs, which negotiate API versions internally, over hand-built protocol requests.","When upgrading the client past the broker version, verify the broker release notes list the new API keys you intend to use."],"tags":["api-versioning","broker-compatibility","client-server","unsupported-version"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}