What causes "Failed to construct Kafka share consumer" in apache/kafka?

Inspect the cause chain of the KafkaException; the root Throwable identifies the failing initialization step.

apache/kafka · critical · KafkaException

Failed to construct Kafka share consumer

Error message

Failed to construct Kafka share consumer

What it means

KafkaException thrown from the ShareConsumerImpl public constructor's outer try/catch when any Throwable escapes during initialization. Distinct from the delegate-creator wrapping: this is the construction site itself — it first attempts close(Duration.ZERO, true) on any partially-built internals (to prevent resource leaks when log is already assigned) and then wraps the cause. So a single failed construction can both clean up and surface a uniform error.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerImpl.java:355

                    logContext,
                    metadata,
                    subscriptions,
                    new ShareFetchConfig(config),
                    deserializers);

            this.kafkaShareConsumerMetrics = new KafkaShareConsumerMetrics(metrics);

            config.logUnused();
            AppInfoParser.registerAppInfo(CONSUMER_JMX_PREFIX, clientId, metrics, time.milliseconds());
            log.debug("Kafka share consumer initialized");
        } catch (Throwable t) {
            // Call close methods if internal objects are already constructed; this is to prevent resource leak.
            // We do not need to call `close` at all when `log` is null, which means no internal objects were initialized.
            if (this.log != null) {
                close(Duration.ZERO, true);
            }
            // Now propagate the exception
            throw new KafkaException("Failed to construct Kafka share consumer", t);
        }
    }

    // Visible for testing
    ShareConsumerImpl(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) {
        this.clientId = clientId;
        this.groupId = groupId;
        this.log = logContext.logger(getClass());
        this.time = time;

View on GitHub (pinned to c31c9215e1)

Solutions

Inspect the cause chain of the KafkaException; the root Throwable identifies the failing initialization step.
If JMX/MBean collision: use a unique client.id per consumer instance or disable JMX reporting in the container.
Verify all required ConsumerConfig keys are present and well-typed (bootstrap.servers, group.id, key/value deserializer, metrics reporters).
Check that deserializer and metrics-reporter classes are on the classpath and their constructors do not throw.
Reproduce in isolation with minimal config to confirm whether the failure is environment-specific (security manager, thread limits).

Defensive patterns

Strategy: try-catch

Validate before calling

// Reduce the surface for init failures by validating config + deserializers first.
try {
    ConsumerConfig cfg = new ConsumerConfig(props); // throws ConfigException for bad keys/values
    keyDeserializer.configure(cfg.originals(Collections.singletonMap("key", "")), true);
    valueDeserializer.configure(cfg.originals(Collections.singletonMap("value", "")), false);
} catch (Exception e) {
    throw new IllegalStateException("Share consumer preconditions failed", e);
}

Try / catch

// The constructor closes partially-built state before rethrowing, so callers
// only need to translate the wrapped KafkaException.
import org.apache.kafka.common.KafkaException;

ShareConsumer<K,V> consumer;
try {
    consumer = new KafkaShareConsumer<>(props, keyDeser, valueDeser);
} catch (KafkaException e) {
    // 'Failed to construct Kafka share consumer' — examine getCause().
    // Common causes: Deserializer instantiate error, SSL/TLS, Metrics, AppInfoParser JMX.
    log.error("Share consumer init failed: {}", e.getCause(), e);
    throw e;
}

Prevention

The constructor calls close(Duration.ZERO, true) on failure — do not also call close() yourself in the catch block.
Deserializer instantiation is the most common culprit; construct and configure them outside and reuse to isolate the failure.
Validate required configs (group.id, bootstrap.servers) before construction — missing required keys throw ConfigException which propagates as the cause.
Run with -Dcom.sun.management.jmxremote=false or unique client ids if AppInfoParser JMX registration clashes.

When it happens

Trigger: Constructing ShareConsumerImpl directly (or via the delegate creator, which then re-wraps). Any step in the constructor body — metrics setup, deserializer wiring, NetworkClientDelegate/RequestManagers/ApplicationEventProcessor supplier builds, AppInfoParser.registerAppInfo, ShareFetchCollector construction — throws. The catch block closes already-built components and re-throws wrapped in KafkaException.

Common situations: Misconfigured metrics reporters (e.g. a reporter class that fails to initialize), JMX registration collision (AppInfoParser.registerAppInfo failing because another MBean with the same clientId is already registered), deserializer configuration errors, broker/bootstrap resolution failures surfacing during initial metadata, or running in a security-restricted environment where thread/selector creation fails. Most often the real cause is a ConfigException or a Reflection/ClassNotFoundException.

Related errors

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