apache/kafka · critical · ConfigException

No resolvable bootstrap urls given in bootstrap.servers

Error message

No resolvable bootstrap urls given in bootstrap.servers

What it means

ConfigException thrown when the loop over bootstrap.servers produces zero resolvable InetSocketAddress entries — every entry was either skipped (empty/null), unresolved (UnknownHostException, silently ignored under use_all_dns_ips), or interrupted. It is a fatal guard: the client refuses to start with no reachable seed broker.

Source

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

        for (String url : urls) {
            if (url != null && !url.isEmpty()) {
                try {
                    String host = getHost(url);
                    Integer port = getPort(url);
                    if (host == null || port == null)
                        throw new ConfigException("Invalid url in " + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + ": " + url);

                    addresses.addAll(resolveAddress(url, host, port, clientDnsLookup));

                } catch (IllegalArgumentException e) {
                    throw new ConfigException("Invalid port in " + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + ": " + url);
                } catch (UnknownHostException e) {
                    throw new ConfigException("Unknown host in " + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + ": " + url);
                }
            }
        }
        if (addresses.isEmpty())
            throw new ConfigException("No resolvable bootstrap urls given in " + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG);
        return addresses;
    }

    /**
     * Create a new channel builder from the provided configuration.
     *
     * @param config client configs
     * @param time the time implementation
     * @param logContext the logging context
     *
     * @return configured ChannelBuilder based on the configs.
     */
    public static ChannelBuilder createChannelBuilder(AbstractConfig config, Time time, LogContext logContext) {
        SecurityProtocol securityProtocol = SecurityProtocol.forName(config.getString(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG));
        String clientSaslMechanism = config.getString(SaslConfigs.SASL_MECHANISM);
        return ChannelBuilders.clientChannelBuilder(securityProtocol, JaasContext.Type.CLIENT, config, null,
                clientSaslMechanism, time, logContext);
    }

View on GitHub (pinned to c31c9215e1)

Solutions

From the client host, resolve each bootstrap hostname individually (nslookup/host) to find which (all) fail.
Correct bootstrap.servers to include at least one resolvable host:port, ideally several for redundancy.
If running in a restricted network, fix DNS or fall back to broker IP literals.
Check the JVM was not interrupted mid-resolution (Thread.interrupted) — a shutdown hook firing during construction can also empty the list.

Example fix

// before
bootstrap.servers=,,
// after
bootstrap.servers=broker1:9092,broker2:9092,broker3:9092

Defensive patterns

Strategy: validation

Validate before calling

// The aggregate failure: every entry either was empty, unresolvable, or
// skipped. Pre-flight: at least one entry must both parse AND resolve.
import java.net.InetAddress;
import org.apache.kafka.common.utils.Utils;

static List<String> resolvableBootstrap(List<String> raw) throws UnknownHostException {
    List<String> ok = new ArrayList<>();
    for (String url : raw) {
        if (url == null || url.isBlank()) continue;
        String host = Utils.getHost(url);
        Integer port = Utils.getPort(url);
        if (host == null || port == null) continue;
        try {
            InetAddress.getAllByName(host);
            ok.add(url);
        } catch (UnknownHostException ignored) { /* skip */ }
    }
    if (ok.isEmpty())
        throw new IllegalStateException("No bootstrap url in " + raw + " is resolvable");
    return ok;
}

Try / catch

try {
    client = AdminClient.create(props);
} catch (ConfigException e) {
    if (e.getMessage().startsWith("No resolvable bootstrap urls")) {
        // Every entry failed. Treat as a startup-blocking config fault;
        // surface to the operator — do NOT silently retry in a loop.
        failHealthCheckAndStop(e);
    } else throw e;
}

Prevention

Run a startup readiness probe that performs the resolve-and-validate step above; refuse to accept traffic until at least one bootstrap url resolves.
Provide multiple brokers in bootstrap.servers (3+) from independent hosts so a single DNS blip does not zero out the list.
Do not put all bootstrap servers behind a single DNS name that itself fails — diversity at the host level is what protects you.
Distinguish 'no resolvable urls' (config/DNS) from 'brokers unreachable' (network) — only the former throws ConfigException at construction.

When it happens

Trigger: All bootstrap entries are unresolvable with client.dns.lookup=use_all_dns_ips (each UnknownHostException is swallowed per the comment at ClientUtils.java:111), or every entry is blank. Triggered by parseAndValidateAddresses returning an empty list.

Common situations: Disaster-recovery / network partition where every broker hostname fails DNS at once, misconfigured client.dns_lookup combined with stale hostnames, or a bootstrap.servers value that is entirely whitespace/commas.

Related errors

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