apache/kafka · error · IllegalStateException

Unexpected error code {} while fetching at offset {} from to

Error message

Unexpected error code {} while fetching at offset {} from topic-partition {}

What it means

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.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/FetchCollector.java:382

                log.debug("Unset the preferred read replica {} for partition {} since we got {} when fetching {}",
                        clearedReplicaId.get(), tp, error, fetchOffset);
            }
        } else if (error == Errors.TOPIC_AUTHORIZATION_FAILED) {
            //we log the actual partition and not just the topic to help with ACL propagation issues in large clusters
            log.warn("Not authorized to read from partition {}.", tp);
            throw new TopicAuthorizationException(Collections.singleton(tp.topic()));
        } else if (error == Errors.UNKNOWN_LEADER_EPOCH) {
            log.debug("Received unknown leader epoch error in fetch for partition {}", tp);
        } else if (error == Errors.UNKNOWN_SERVER_ERROR) {
            log.warn("Unknown server error while fetching offset {} for topic-partition {}",
                    fetchOffset, tp);
        } else if (error == Errors.CORRUPT_MESSAGE) {
            throw new KafkaException("Encountered corrupt message when fetching offset "
                    + fetchOffset
                    + " for topic-partition "
                    + tp);
        } else {
            throw new IllegalStateException("Unexpected error code "
                    + error.code()
                    + " while fetching at offset "
                    + fetchOffset
                    + " from topic-partition " + tp);
        }
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. Read the numeric error code from the message and check Errors.java in the broker/client source for its meaning.
2. Upgrade the kafka-clients dependency to a version at least as new as the broker so the new error code is handled.
3. If upgrading is blocked, align the broker version down to match the client.
4. 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.

Example fix

// before
<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>3.4.0</version>
</dependency>

// after - match broker version
<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>3.7.0</version>
</dependency>

try {
    ConsumerRecords<K,V> records = consumer.poll(Duration.ofMillis(timeoutMs));
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unexpected error code")) {
        log.error("Protocol/version mismatch with broker on fetch; upgrading client or rolling back broker is required: {}", e.getMessage());
        // surface to operator; not retriable as-is
        throw e;
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Encountered corrupt message when fetching offset {} for topi
• Buffer underflow while parsing response for request with hea
• Unknown rebalance protocol id: {id}
• To use the group management or offset commit APIs, you must
• The target time for partition {} is {}. The target time cann

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/178633a4f81ba884.json. Report an issue: GitHub.