What causes "Failed to create new NetworkClient" in apache/kafka?

Read the 'Caused by:' / cause of the KafkaException — that exception names the real problem; the NetworkClient message is only the envelope.

apache/kafka · error · KafkaException

Failed to create new NetworkClient

Error message

Failed to create new NetworkClient

What it means

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).

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/ClientUtils.java:285

                    requestTimeoutMs,
                    config.getLong(CommonClientConfigs.SOCKET_CONNECTION_SETUP_TIMEOUT_MS_CONFIG),
                    config.getLong(CommonClientConfigs.SOCKET_CONNECTION_SETUP_TIMEOUT_MAX_MS_CONFIG),
                    time,
                    true,
                    apiVersions,
                    throttleTimeSensor,
                    logContext,
                    hostResolver,
                    clientTelemetrySender,
                    config.getLong(CommonClientConfigs.METADATA_RECOVERY_REBOOTSTRAP_TRIGGER_MS_CONFIG),
                    MetadataRecoveryStrategy.forName(config.getString(CommonClientConfigs.METADATA_RECOVERY_STRATEGY_CONFIG)),
                    bootstrapConfiguration,
                    config.getBoolean(CommonClientConfigs.METADATA_CLUSTER_CHECK_ENABLE_CONFIG)
            );
        } catch (Throwable t) {
            closeQuietly(selector, "Selector");
            closeQuietly(channelBuilder, "ChannelBuilder");
            throw new KafkaException("Failed to create new NetworkClient", t);
        }
    }

    public static <T> List<?> configuredInterceptors(AbstractConfig config,
                                                    String interceptorClassesConfigName,
                                                    Class<T> clazz) {
        String clientId = config.getString(CommonClientConfigs.CLIENT_ID_CONFIG);
        return config.getConfiguredInstances(
                interceptorClassesConfigName,
                clazz,
                Collections.singletonMap(CommonClientConfigs.CLIENT_ID_CONFIG, clientId));
    }

    public static ClusterResourceListeners configureClusterResourceListeners(List<?>... candidateLists) {
        ClusterResourceListeners clusterResourceListeners = new ClusterResourceListeners();

        for (List<?> candidateList: candidateLists)
            clusterResourceListeners.maybeAddAll(candidateList);

View on GitHub (pinned to c31c9215e1)

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.

Example fix

// before
props.put("security.protocol", "SSL");
props.put("ssl.truststore.location", "/missing/client.truststore.jks"); // FileNotFoundException in cause
// after
props.put("ssl.truststore.location", "/etc/kafka/client.truststore.jks");

Defensive patterns

Strategy: try-catch

Validate before calling

// NetworkClient creation wraps arbitrary Throwables (SSL misconfig,
// ChannelBuilder failures, bad SASL/JAAS, Selector errors) into a single
// KafkaException. There is no single pre-check; instead, run an isolated
// 'warm-up' that exercises the same code path before going live:
try {
    AdminClient.create(props).close();   // smoke test the channel builder
} catch (KafkaException e) {
    log.error("Client config is invalid at startup: {}", e.getCause(), e);
    // fail the deploy / refuse to start the service.
    throw e;
}

Try / catch

// The cause (getCause()) carries the real reason; surface it.
try {
    this.producer = new KafkaProducer<>(props);
} catch (org.apache.kafka.common.KafkaException e) {
    Throwable cause = e.getCause();
    if (cause instanceof org.apache.kafka.common.config.ConfigException)
        throw new ConfigurationException("Kafka config invalid", cause);
    if (cause instanceof java.io.IOException || cause instanceof javax.naming.NamingException)
        log.warn("Channel/SSL setup failed; will retry client creation on backoff", cause);
    else
        throw e;   // unknown — propagate
}

Prevention

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.

When it happens

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

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

Related errors

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