{"id":"178633a4f81ba884","repo":"apache/kafka","slug":"unexpected-error-code-while-fetching-at-offset","errorCode":null,"errorMessage":"Unexpected error code {} while fetching at offset {} from topic-partition {}","messagePattern":"Unexpected error code (.+?) while fetching at offset (.+?) from topic-partition (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/FetchCollector.java","lineNumber":382,"sourceCode":"                log.debug(\"Unset the preferred read replica {} for partition {} since we got {} when fetching {}\",\n                        clearedReplicaId.get(), tp, error, fetchOffset);\n            }\n        } else if (error == Errors.TOPIC_AUTHORIZATION_FAILED) {\n            //we 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);\n            throw new TopicAuthorizationException(Collections.singleton(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 offset {} for topic-partition {}\",\n                    fetchOffset, tp);\n        } else if (error == Errors.CORRUPT_MESSAGE) {\n            throw new KafkaException(\"Encountered corrupt message when fetching offset \"\n                    + fetchOffset\n                    + \" for topic-partition \"\n                    + tp);\n        } else {\n            throw new IllegalStateException(\"Unexpected error code \"\n                    + error.code()\n                    + \" while fetching at offset \"\n                    + fetchOffset\n                    + \" from topic-partition \" + tp);\n        }\n    }\n}\n","sourceCodeStart":364,"sourceCodeEnd":390,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/FetchCollector.java#L364-L390","documentation":"Thrown as IllegalStateException from the default branch of FetchCollector.handleInitializeErrors when a FetchResponse carries an Errors code the client does not explicitly handle. It indicates a protocol-level mismatch: the broker returned an error code (typically from a newer broker release) that this consumer client version does not know how to interpret. Because the fetch path has handled every known recoverable error above, falling through to default means the client cannot safely continue.","triggerScenarios":"Produced when poll() receives a FetchResponse whose partition error code is not one of NOT_LEADER_OR_FOLLOWER, REPLICA_NOT_AVAILABLE, KAFKA_STORAGE_ERROR, FENCED_LEADER_EPOCH, UNKNOWN_LEADER_EPOCH, OFFSET_OUT_OF_RANGE, UNKNOWN_TOPIC_OR_PARTITION, TOPIC_AUTHORIZATION_FAILED, UNKNOWN_TOPIC_ID, INCONSISTENT_TOPIC_ID, UNKNOWN_SERVER_ERROR, or CORRUPT_MESSAGE. Most common when broker version is newer than client.","commonSituations":"Client/broker version skew (e.g. old client against a new broker that emits a newly introduced error code), a broker bug returning an unexpected code, or after an upgrade before the client is refreshed. The exception message includes the numeric code for diagnosis.","solutions":["Read the numeric error code from the message and check Errors.java in the broker/client source for its meaning.","Upgrade the kafka-clients dependency to a version at least as new as the broker so the new error code is handled.","If upgrading is blocked, align the broker version down to match the client.","Report the code to the Kafka dev list if it is not documented, since hitting this default branch is itself a signal of a version gap."],"exampleFix":"// before\n<dependency>\n  <groupId>org.apache.kafka</groupId>\n  <artifactId>kafka-clients</artifactId>\n  <version>3.4.0</version>\n</dependency>\n\n// after - match broker version\n<dependency>\n  <groupId>org.apache.kafka</groupId>\n  <artifactId>kafka-clients</artifactId>\n  <version>3.7.0</version>\n</dependency>","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    ConsumerRecords<K,V> records = consumer.poll(Duration.ofMillis(timeoutMs));\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unexpected error code\")) {\n        log.error(\"Protocol/version mismatch with broker on fetch; upgrading client or rolling back broker is required: {}\", e.getMessage());\n        // surface to operator; not retriable as-is\n        throw e;\n    }\n    throw e;\n}","preventionTips":["Keep the client library version within the supported compatibility matrix of the broker cluster.","Rolling-upgrade brokers fully before introducing new error codes that older clients cannot interpret.","Subscribe to KIP releases that add new Errors codes and bump clients in lockstep.","Log the numeric error code alongside the exception so operators can map it back to a broker-side condition.","Do not swallow this exception silently; it indicates the client cannot make sense of broker responses."],"tags":["kafka","consumer","version-mismatch","protocol","fetch"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}