{"id":"4112ed67688464c7","repo":"apache/kafka","slug":"failed-to-construct-kafka-share-consumer","errorCode":null,"errorMessage":"Failed to construct Kafka share consumer","messagePattern":"Failed to construct Kafka share consumer","errorType":"exception","errorClass":"KafkaException","httpStatus":null,"severity":"critical","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerDelegateCreator.java","lineNumber":48,"sourceCode":" * underlying {@link ShareConsumer} implementation that is created. This provides the means by which\n * {@link KafkaShareConsumer} can remain the top-level facade for implementations, but allow different implementations\n * to co-exist under the covers.\n *\n * <p>\n * <em>Note</em>: this is for internal use only and is not intended for use by end users. Internal users should\n * not attempt to determine the underlying implementation to avoid coding to an unstable interface. Rather, it is\n * the {@link ShareConsumer} API contract that should serve as the caller's interface.\n */\npublic class ShareConsumerDelegateCreator {\n    public <K, V> ShareConsumerDelegate<K, V> create(final ConsumerConfig config,\n                                                     final Deserializer<K> keyDeserializer,\n                                                     final Deserializer<V> valueDeserializer) {\n        try {\n            return new ShareConsumerImpl<>(config, keyDeserializer, valueDeserializer);\n        } catch (KafkaException e) {\n            throw e;\n        } catch (Throwable t) {\n            throw new KafkaException(\"Failed to construct Kafka share consumer\", t);\n        }\n    }\n\n    public <K, V> ShareConsumerDelegate<K, V> create(final LogContext logContext,\n                                                     final String clientId,\n                                                     final String groupId,\n                                                     final ConsumerConfig config,\n                                                     final Deserializer<K> keyDeserializer,\n                                                     final Deserializer<V> valueDeserializer,\n                                                     final Time time,\n                                                     final KafkaClient client,\n                                                     final SubscriptionState subscriptions,\n                                                     final ShareConsumerMetadata metadata) {\n        try {\n            return new ShareConsumerImpl<>(\n                    logContext,\n                    clientId,\n                    groupId,","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerDelegateCreator.java#L30-L66","documentation":"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.'","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the exception's cause (Throwable t) — it carries the real underlying error and stack trace.","Reproduce with the exact ConsumerConfig + deserializers in a unit test to isolate which constructor step fails.","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.","If the cause is a KafkaException in disguise, fix it directly (e.g. ConfigException -> correct the named key)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// No deterministic pre-check: any Throwable from internal init is wrapped here.\n// Validate the inputs you control before constructing:\nif (config == null || keyDeserializer == null || valueDeserializer == null) {\n    throw new IllegalArgumentException(\"ConsumerConfig and deserializers must be non-null\");\n}","typeGuard":null,"tryCatchPattern":"// Wrap the primary create() call; the wrapper rethrows KafkaException with cause.\nimport org.apache.kafka.common.KafkaException;\n\nShareConsumerDelegate<K,V> delegate;\ntry {\n    delegate = new ShareConsumerDelegateCreator()\n        .create(config, keyDeserializer, valueDeserializer);\n} catch (KafkaException e) {\n    // 'Failed to construct Kafka share consumer' — inspect getCause() for the real reason\n    log.error(\"Could not build share consumer: {}\", e.getCause(), e);\n    throw new MyConsumerInitException(e.getCause());\n}","preventionTips":["Inspect getCause() — the real failure (e.g. Deserializer, SSL, unknown config) is masked by the wrapper.","Unit-test deserializer instantiation separately so a bad deserializer does not blow up consumer creation.","Validate non-null config + deserializers before calling; this method does not guard them for you.","Do not retry construction in a tight loop — most causes (bad config, missing class) are deterministic."],"tags":["kafka","share-consumer","initialization","construction"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}