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

Inspect the exception's getCause() (or the wrapped stack trace) — the actual failure and config key are described there, not in this outer message.

apache/kafka · error · KafkaException

Failed to create new KafkaAdminClient

Error message

Failed to create new KafkaAdminClient

What it means

A wrapper KafkaException thrown by the catch-all in KafkaAdminClient.createInternal when any Throwable escapes while building the Metrics, NetworkClient, or AdminClientRunnable (e.g. invalid config values, SSL/TLS misconfiguration, SASL errors, DNS/resolver failures, or any earlier ConfigException). The original cause is attached as exc via the exception constructor, so resolving it requires inspecting getCause() — the outer message alone only signals that admin client construction failed.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java:623

                clientId,
                metrics,
                "admin-client",
                logContext,
                apiVersions,
                time,
                1,
                (int) TimeUnit.HOURS.toMillis(1),
                null,
                metadataManager.updater(),
                (hostResolver == null) ? new DefaultHostResolver() : hostResolver,
                null,
                clientTelemetryReporter.map(ClientTelemetryReporter::telemetrySender).orElse(null));
            return new KafkaAdminClient(config, clientId, time, metadataManager, metrics, networkClient,
                timeoutProcessorFactory, logContext, clientTelemetryReporter);
        } catch (Throwable exc) {
            closeQuietly(metrics, "Metrics");
            closeQuietly(networkClient, "NetworkClient");
            throw new KafkaException("Failed to create new KafkaAdminClient", exc);
        }
    }

    // Visible for tests
    static KafkaAdminClient createInternal(AdminClientConfig config,
                                           AdminMetadataManager metadataManager,
                                           KafkaClient client,
                                           Time time) {
        Metrics metrics = null;
        String clientId = generateClientId(config);
        List<MetricsReporter> reporters = CommonClientConfigs.metricsReporters(clientId, config);
        Optional<ClientTelemetryReporter> clientTelemetryReporter = CommonClientConfigs.telemetryReporter(clientId, config);
        clientTelemetryReporter.ifPresent(reporters::add);

        try {
            metrics = new Metrics(new MetricConfig(), reporters, time);
            LogContext logContext = createLogContext(clientId);
            return new KafkaAdminClient(config, clientId, time, metadataManager, metrics,

View on GitHub (pinned to c31c9215e1)

Solutions

Inspect the exception's getCause() (or the wrapped stack trace) — the actual failure and config key are described there, not in this outer message.
Fix the root cause identified by the wrapped exception (correct the config value, keystore path, SASL config, etc.).
Enable DEBUG/TRACE logging for org.apache.kafka.clients.admin and org.apache.kafka.common.network to see the failure before it is wrapped.
Validate the Admin config programmatically by constructing AdminClientConfig directly first (new AdminClientConfig(props)) so misconfigurations surface as ConfigException before the heavier NetworkClient build.

Example fix

// before
try {
    Admin admin = Admin.create(props);
} catch (KafkaException e) {
    log.error("Failed to create admin: {}", e.getMessage()); // only sees the wrapper
}

// after - unwrap and log the real cause
try {
    Admin admin = Admin.create(props);
} catch (KafkaException e) {
    Throwable cause = e.getCause() != null ? e.getCause() : e;
    log.error("Failed to create admin (root cause: {})", cause.getMessage(), cause);
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    Admin admin = Admin.create(props);
} catch (KafkaException e) {
    // Wrapper: the real cause lives in e.getCause() (ConfigException, UnknownHostException, SSL errors, ...)
    Throwable cause = e.getCause() != null ? e.getCause() : e;
    log.error("Failed to create KafkaAdminClient: {}", cause.toString());
}

Prevention

Always inspect KafkaException.getCause() — 'Failed to create new KafkaAdminClient' only wraps the real failure (DNS, TLS, SASL, bad config).
Validate all config keys and endpoint reachability (DNS resolve, port open) before calling Admin.create in a hot path.
Treat Admin creation as a fallible, side-effecting operation: build it once, cache it, and never recreate per request.

When it happens

Trigger: Any failure during Admin.create inside createInternal: a ConfigException from an invalid numeric/duration value, an IllegalArgumentException from ClientUtils.createNetworkClient, SSL/SASL/keystore errors, or a RuntimeException from Metrics/telemetry reporter setup. The catch wraps every such failure in this KafkaException and closes the partially-built Metrics and NetworkClient.

Common situations: Wrong type or out-of-range value for request.timeout.ms, metadata.max.age.ms, etc.; missing/unreadable SSL keystore or truststore path; SASL mechanism misconfigured; a custom MetricsReporter constructor that throws; typo'd config keys that map to a wrong type after originals() processing.

Related errors

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