{"id":"7a9d681eb1c76211","repo":"apache/kafka","slug":"unexpected-error-code-error-code-while-fetchi","errorCode":null,"errorMessage":"Unexpected error code ${error.code()} while fetching from topic-partition ${tp.topicPartition()}","messagePattern":"Unexpected error code (.+?) while fetching from topic-partition (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareFetchCollector.java","lineNumber":185,"sourceCode":"            log.warn(\"Received unknown topic ID error in fetch for partition {}.\", tp);\n            requestMetadataUpdate(metadata, subscriptions, tp.topicPartition());\n        } else if (error == Errors.INCONSISTENT_TOPIC_ID) {\n            log.warn(\"Received inconsistent topic ID error in fetch for partition {}.\", tp);\n            requestMetadataUpdate(metadata, subscriptions, tp.topicPartition());\n        } else if (error == Errors.TOPIC_AUTHORIZATION_FAILED) {\n            // Log the actual partition and not just the topic to help with ACL propagation issues in large clusters\n            log.warn(\"Not authorized to read from partition {}.\", tp.topicPartition());\n            throw new TopicAuthorizationException(Set.of(tp.topic()));\n        } else if (error == Errors.UNKNOWN_LEADER_EPOCH) {\n            log.debug(\"Received unknown leader epoch error in fetch for partition {}.\", tp);\n        } else if (error == Errors.UNKNOWN_SERVER_ERROR) {\n            log.warn(\"Unknown server error while fetching topic-partition {}.\",\n                    tp.topicPartition());\n        } else if (error == Errors.CORRUPT_MESSAGE) {\n            throw new KafkaException(\"Encountered corrupt message when fetching topic-partition \"\n                    + tp.topicPartition());\n        } else {\n            throw new IllegalStateException(\"Unexpected error code \" + error.code()\n                    + \" while fetching from topic-partition \" + tp.topicPartition());\n        }\n    }\n}\n","sourceCodeStart":167,"sourceCodeEnd":190,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareFetchCollector.java#L167-L190","documentation":"Thrown by ShareFetchCollector.handleInitializeErrors for any fetch error code not handled by the explicit branches (NOT_LEADER_OR_FOLLOWER, AUTHORIZATION, CORRUPT_MESSAGE, etc.). It is a defensive guard: the share consumer encountered an Errors enum value it does not expect for share fetches and refuses to proceed, surfacing the numeric code and partition so the operator can map it via org.apache.kafka.common.protocol.Errors.","triggerScenarios":"A new or rare error code (e.g. broker-version-specific code, SHARE_SESSION_NOT_FOUND, or an unreleased error) reaches the fetch collector's switch. Also seen when the client and broker versions diverge and the broker emits a code the client's Errors enum did not classify as a fetch-recoverable error.","commonSituations":"Client/broker version skew; using a share consumer against a broker that does not implement KIP-932 fully; broker returns an error code introduced after the client was built; future or experimental error codes the client's branch has not mapped.","solutions":["Map the numeric code to its name via org.apache.kafka.common.protocol.Errors.forCode(code) to identify the underlying condition.","Align client and broker versions so both sides share the same Errors classification.","Check broker logs around the same timestamp for the originating condition (e.g. coordinator error, quota violation).","If the code is genuinely unhandled in this client version, upgrade the kafka-clients dependency to one that supports share groups."],"exampleFix":"// before\n} else {\n    throw new IllegalStateException(\"Unexpected error code \" + error.code() + \" ...\");\n}\n\n// diagnosis step in user code\nErrors e = Errors.forCode(receivedCode);\nlog.error(\"fetch error name={} message={}\", e.name(), e.message());","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    records = consumer.poll(Duration.ofSeconds(5));\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unexpected error code\")) {\n        // The broker returned an error code this client version does not understand:\n        // client/broker version skew. Upgrade the client to match the broker, then retry.\n        log.error(\"Client/broker version skew: {}\", e.getMessage(), e);\n        throw new NonRecoverableKafkaException(e);\n    }\n    throw e;\n}","preventionTips":["Keep the client version >= the broker's inter-broker protocol version.","Read the broker server log for the numeric error code and map it against the current Errors enum.","Pin client versions in CI so an unintended bump does not reach production.","Treat this as a hard failure: retrying will not help until versions are aligned."],"tags":["share-consumer","version-skew","protocol","kafka-client"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}