apache/kafka · critical · KafkaException

Failed to construct Kafka share consumer

Error message

Failed to construct Kafka share consumer

What it means

Generic KafkaException thrown by ShareConsumerDelegateCreator.create(config, keyDeser, valueDeser) when constructing the ShareConsumerImpl fails with any non-KafkaException Throwable. KafkaException subclasses are re-thrown as-is to preserve their specific semantics; everything else is wrapped so callers see a single, typed failure during the standard public construction path. It exists to give a stable contract: 'consumer construction either returns a working consumer or throws KafkaException.'

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerDelegateCreator.java:48

 * underlying {@link ShareConsumer} implementation that is created. This provides the means by which
 * {@link KafkaShareConsumer} can remain the top-level facade for implementations, but allow different implementations
 * to co-exist under the covers.
 *
 * <p>
 * <em>Note</em>: this is for internal use only and is not intended for use by end users. Internal users should
 * not attempt to determine the underlying implementation to avoid coding to an unstable interface. Rather, it is
 * the {@link ShareConsumer} API contract that should serve as the caller's interface.
 */
public class ShareConsumerDelegateCreator {
    public <K, V> ShareConsumerDelegate<K, V> create(final ConsumerConfig config,
                                                     final Deserializer<K> keyDeserializer,
                                                     final Deserializer<V> valueDeserializer) {
        try {
            return new ShareConsumerImpl<>(config, keyDeserializer, valueDeserializer);
        } catch (KafkaException e) {
            throw e;
        } catch (Throwable t) {
            throw new KafkaException("Failed to construct Kafka share consumer", t);
        }
    }

    public <K, V> ShareConsumerDelegate<K, V> create(final LogContext logContext,
                                                     final String clientId,
                                                     final String groupId,
                                                     final ConsumerConfig config,
                                                     final Deserializer<K> keyDeserializer,
                                                     final Deserializer<V> valueDeserializer,
                                                     final Time time,
                                                     final KafkaClient client,
                                                     final SubscriptionState subscriptions,
                                                     final ShareConsumerMetadata metadata) {
        try {
            return new ShareConsumerImpl<>(
                    logContext,
                    clientId,
                    groupId,

View on GitHub (pinned to c31c9215e1)

Solutions

  1. Read the exception's cause (Throwable t) — it carries the real underlying error and stack trace.
  2. Reproduce with the exact ConsumerConfig + deserializers in a unit test to isolate which constructor step fails.
  3. Verify deserializer classes are on the classpath and that all required config keys (bootstrap servers, group.id, key/value deserializer) are present and correctly typed.
  4. If the cause is a KafkaException in disguise, fix it directly (e.g. ConfigException -> correct the named key).
Defensive patterns

Strategy: try-catch

Validate before calling

// No deterministic pre-check: any Throwable from internal init is wrapped here.
// Validate the inputs you control before constructing:
if (config == null || keyDeserializer == null || valueDeserializer == null) {
    throw new IllegalArgumentException("ConsumerConfig and deserializers must be non-null");
}

Try / catch

// Wrap the primary create() call; the wrapper rethrows KafkaException with cause.
import org.apache.kafka.common.KafkaException;

ShareConsumerDelegate<K,V> delegate;
try {
    delegate = new ShareConsumerDelegateCreator()
        .create(config, keyDeserializer, valueDeserializer);
} catch (KafkaException e) {
    // 'Failed to construct Kafka share consumer' — inspect getCause() for the real reason
    log.error("Could not build share consumer: {}", e.getCause(), e);
    throw new MyConsumerInitException(e.getCause());
}

Prevention

When it happens

Trigger: Calling new KafkaShareConsumer<>(config, keyDeserializer, valueDeserializer) (which routes through ShareConsumerDelegateCreator.create) and the ShareConsumerImpl constructor throws something that is not a KafkaException — e.g. NullPointerException, IllegalStateException, ReflectiveOperationException, or a third-party deserializer/init exception.

Common situations: A custom Deserializer whose constructor throws, a missing or incompatible config key causing an NPE during initialization, classpath issues where a configured class cannot be loaded, or a wrong-type config value (e.g. passing a String where an Integer is expected) surfacing as a RuntimeException. The original cause is attached as the exception's cause.

Related errors

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