apache/kafka · error · IllegalStateException

Unexpected error code ${error.code()} while fetching from to

Error message

Unexpected error code ${error.code()} while fetching from topic-partition ${tp.topicPartition()}

What it means

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.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareFetchCollector.java:185

            log.warn("Received unknown topic ID error in fetch for partition {}.", tp);
            requestMetadataUpdate(metadata, subscriptions, tp.topicPartition());
        } else if (error == Errors.INCONSISTENT_TOPIC_ID) {
            log.warn("Received inconsistent topic ID error in fetch for partition {}.", tp);
            requestMetadataUpdate(metadata, subscriptions, tp.topicPartition());
        } else if (error == Errors.TOPIC_AUTHORIZATION_FAILED) {
            // 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.topicPartition());
            throw new TopicAuthorizationException(Set.of(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 topic-partition {}.",
                    tp.topicPartition());
        } else if (error == Errors.CORRUPT_MESSAGE) {
            throw new KafkaException("Encountered corrupt message when fetching topic-partition "
                    + tp.topicPartition());
        } else {
            throw new IllegalStateException("Unexpected error code " + error.code()
                    + " while fetching from topic-partition " + tp.topicPartition());
        }
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. Map the numeric code to its name via org.apache.kafka.common.protocol.Errors.forCode(code) to identify the underlying condition.
2. Align client and broker versions so both sides share the same Errors classification.
3. Check broker logs around the same timestamp for the originating condition (e.g. coordinator error, quota violation).
4. If the code is genuinely unhandled in this client version, upgrade the kafka-clients dependency to one that supports share groups.

Example fix

// before
} else {
    throw new IllegalStateException("Unexpected error code " + error.code() + " ...");
}

// diagnosis step in user code
Errors e = Errors.forCode(receivedCode);
log.error("fetch error name={} message={}", e.name(), e.message());

try {
    records = consumer.poll(Duration.ofSeconds(5));
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unexpected error code")) {
        // The broker returned an error code this client version does not understand:
        // client/broker version skew. Upgrade the client to match the broker, then retry.
        log.error("Client/broker version skew: {}", e.getMessage(), e);
        throw new NonRecoverableKafkaException(e);
    }
    throw e;
}

When it happens

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

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

Related errors

• Unknown share acquire mode id: {}
• Consumer is not subscribed to any topics.
• Telemetry is not enabled. Set config `${ConsumerConfig.ENABL
• Failed to close Kafka share consumer
• This consumer has already been closed.

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