apache/kafka · error · KafkaException

Failed to create new NetworkClient

Error message

Failed to create new NetworkClient

What it means

KafkaException thrown by ClientUtils.createNetworkClient wrapping any Throwable raised while constructing the NetworkClient (or the selector/channelBuilder prepared just before it). It cleans up by closing the selector and channelBuilder before rethrowing, so partial resources are not leaked. The cause identifies the real failure (config, IO, DNS, channel-builder, telemetry-sender, etc.).

Solutions

  1. Read the wrapped cause (t.getCause()) — it names the actual config or construction problem.
  2. Fix the underlying issue (bootstrap URL, SASL mechanism, metadata.recovery.strategy, etc.).
  3. Enable DEBUG/TRACE logging for org.apache.kafka.clients to see which construction step failed.
  4. If integrating NetworkClient directly, ensure all non-null args (hostResolver, telemetrySender, bootstrapConfiguration) are provided.
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate the components that commonly cause NetworkClient construction failure
Objects.requireNonNull(hostResolver, "hostResolver");
Objects.requireNonNull(clientTelemetrySender, "clientTelemetrySender");
MetadataRecoveryStrategy.forName(strategyName); // surfaces bad value early
BootstrapConfiguration.enabled(bootstrapServers, dns, t, backoff);

Try / catch

try { ClientUtils.createNetworkClient(...); } catch (KafkaException e) { Throwable c = e.getCause(); /* inspect c: ConfigException -> fix config; IllegalArgumentException -> bad enum/arg; etc. */ throw e; }

Prevention

When it happens

Trigger: catch (Throwable t) at line 276 wraps anything thrown by BootstrapConfiguration.enabled(...) or the new NetworkClient(...) constructor (lines 246-275). Common causes: ConfigException from bad bootstrap.servers, IllegalArgument from MetadataRecoveryStrategy.forName, channel-builder/SASL misconfiguration, NPE from a null dependency passed in.

Common situations: Invalid metadata.recovery.strategy value (see error 19); bad bootstrap.servers; missing/invalid SASL or SSL config; null hostResolver or clientTelemetrySender; incompatible config combos caught inside NetworkClient.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/b18894e3cf689bc0. Report an issue: GitHub.

Appendix: source

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

                    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 996fb4585a)