{"id":"b18894e3cf689bc0","repo":"apache/kafka","slug":"failed-to-create-new-networkclient","errorCode":null,"errorMessage":"Failed to create new NetworkClient","messagePattern":"Failed to create new NetworkClient","errorType":"exception","errorClass":"KafkaException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/ClientUtils.java","lineNumber":285,"sourceCode":"                    requestTimeoutMs,\n                    config.getLong(CommonClientConfigs.SOCKET_CONNECTION_SETUP_TIMEOUT_MS_CONFIG),\n                    config.getLong(CommonClientConfigs.SOCKET_CONNECTION_SETUP_TIMEOUT_MAX_MS_CONFIG),\n                    time,\n                    true,\n                    apiVersions,\n                    throttleTimeSensor,\n                    logContext,\n                    hostResolver,\n                    clientTelemetrySender,\n                    config.getLong(CommonClientConfigs.METADATA_RECOVERY_REBOOTSTRAP_TRIGGER_MS_CONFIG),\n                    MetadataRecoveryStrategy.forName(config.getString(CommonClientConfigs.METADATA_RECOVERY_STRATEGY_CONFIG)),\n                    bootstrapConfiguration,\n                    config.getBoolean(CommonClientConfigs.METADATA_CLUSTER_CHECK_ENABLE_CONFIG)\n            );\n        } catch (Throwable t) {\n            closeQuietly(selector, \"Selector\");\n            closeQuietly(channelBuilder, \"ChannelBuilder\");\n            throw new KafkaException(\"Failed to create new NetworkClient\", t);\n        }\n    }\n\n    public static <T> List<?> configuredInterceptors(AbstractConfig config,\n                                                    String interceptorClassesConfigName,\n                                                    Class<T> clazz) {\n        String clientId = config.getString(CommonClientConfigs.CLIENT_ID_CONFIG);\n        return config.getConfiguredInstances(\n                interceptorClassesConfigName,\n                clazz,\n                Collections.singletonMap(CommonClientConfigs.CLIENT_ID_CONFIG, clientId));\n    }\n\n    public static ClusterResourceListeners configureClusterResourceListeners(List<?>... candidateLists) {\n        ClusterResourceListeners clusterResourceListeners = new ClusterResourceListeners();\n\n        for (List<?> candidateList: candidateLists)\n            clusterResourceListeners.maybeAddAll(candidateList);","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/ClientUtils.java#L267-L303","documentation":"KafkaException wrapping any Throwable raised while assembling the NetworkClient (channel builder, Selector, BootstrapConfiguration). The catch block at ClientUtils.java:282 closes the partially-built Selector and ChannelBuilder and re-throws the original as the cause, so the client cannot leak resources but also cannot start. It is a generic envelope for a wide range of underlying failures (security misconfig, SASL errors, bad config values).","triggerScenarios":"Any error during createChannelBuilder (e.g. SSL keystore not found, SASL mechanism invalid), Selector construction, BootstrapConfiguration.enabled, or NetworkClient instantiation. Surfaced to the caller as 'Failed to create new NetworkClient' with a non-null cause.","commonSituations":"First client construction after a config change: bad ssl.truststore location, JAAS config syntax error, unsupported sasl.mechanism, missing required security config, or a corrupted kafka-clients jar. Also hit when reflection/instantiation of a ChannelBuilder fails.","solutions":["Read the 'Caused by:' / cause of the KafkaException — that exception names the real problem; the NetworkClient message is only the envelope.","Address the root cause: fix the SSL/SASL config, restore the truststore, correct sasl.mechanism, etc.","Re-run a minimal config (PLAINTEXT, no SASL) to isolate whether the failure is security-related or a packaging issue.","If the cause is a ClassNotFoundException or NoClassDefFoundError, reconcile kafka-clients version and shade/exclude conflicts on the classpath."],"exampleFix":"// before\nprops.put(\"security.protocol\", \"SSL\");\nprops.put(\"ssl.truststore.location\", \"/missing/client.truststore.jks\"); // FileNotFoundException in cause\n// after\nprops.put(\"ssl.truststore.location\", \"/etc/kafka/client.truststore.jks\");","handlingStrategy":"try-catch","validationCode":"// NetworkClient creation wraps arbitrary Throwables (SSL misconfig,\n// ChannelBuilder failures, bad SASL/JAAS, Selector errors) into a single\n// KafkaException. There is no single pre-check; instead, run an isolated\n// 'warm-up' that exercises the same code path before going live:\ntry {\n    AdminClient.create(props).close();   // smoke test the channel builder\n} catch (KafkaException e) {\n    log.error(\"Client config is invalid at startup: {}\", e.getCause(), e);\n    // fail the deploy / refuse to start the service.\n    throw e;\n}","typeGuard":null,"tryCatchPattern":"// The cause (getCause()) carries the real reason; surface it.\ntry {\n    this.producer = new KafkaProducer<>(props);\n} catch (org.apache.kafka.common.KafkaException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof org.apache.kafka.common.config.ConfigException)\n        throw new ConfigurationException(\"Kafka config invalid\", cause);\n    if (cause instanceof java.io.IOException || cause instanceof javax.naming.NamingException)\n        log.warn(\"Channel/SSL setup failed; will retry client creation on backoff\", cause);\n    else\n        throw e;   // unknown — propagate\n}","preventionTips":["Always log KafkaException.getCause() — the outer message ('Failed to create new NetworkClient') is generic; the cause names the actual fault (SslEngineConfigurationException, IllegalArgumentException, IOException, etc.).","Validate SSL/SASL configs in a staging environment with the same keystores/jaas files; the majority of NetworkClient creation failures are channel-builder misconfigs.","Run an AdminClient.create(...).close() smoke test at process startup so channel errors surface during boot rather than on the first produce/consume.","Keep your JAAS config, keystore passwords, and truststore paths in a single source of truth; mismatches between them are the most common cause."],"tags":["client","network","security","startup"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}