What causes "Unknown host in bootstrap.servers: {url}" in apache/kafka?

From the client host, run 'nslookup ' or 'getent hosts ' to confirm DNS resolves.

apache/kafka · error · ConfigException

Unknown host in bootstrap.servers: {url}

Error message

Unknown host in bootstrap.servers: {url}

What it means

ConfigException thrown when an entry's host cannot be resolved to an InetAddress while client.dns.lookup is NOT use_all_dns_ips (the default reverse-dns behaviour throws UnknownHostException, caught and re-wrapped here). It signals a syntactically valid host:port whose name DNS cannot resolve from the client JVM at construction time.

Source

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

        return parseAndValidateAddresses(urls, ClientDnsLookup.forConfig(clientDnsLookupConfig));
    }

    public static List<InetSocketAddress> parseAndValidateAddresses(List<String> urls, ClientDnsLookup clientDnsLookup) {
        List<InetSocketAddress> addresses = new ArrayList<>();
        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) {

View on GitHub (pinned to c31c9215e1)

Solutions

From the client host, run 'nslookup <host>' or 'getent hosts <host>' to confirm DNS resolves.
Fix the hostname in bootstrap.servers or correct the client's DNS / /etc/hosts / search domain so the name resolves.
Verify the broker's advertised.listeners matches a name clients can resolve.

Example fix

// before
bootstrap.servers=broker.internal:9092   // not resolvable from client host
// after
bootstrap.servers=10.0.0.5:9092            // reachable IP, or fix DNS to resolve broker.internal

Defensive patterns

Strategy: validation

Validate before calling

// Resolve the host up front so an unresolvable name is caught at startup,
// not later inside ClientUtils. NOTE: DNS may be transient — if resolution
// fails, retry once after a short backoff before declaring the config bad.
import java.net.InetAddress;

static void checkResolvable(List<String> servers) throws UnknownHostException {
    UnknownHostException last = null;
    for (String url : servers) {
        String host = Utils.getHost(url);
        if (host == null) continue;
        try {
            InetAddress.getAllByName(host);
        } catch (UnknownHostException e) {
            last = e;        // collect but keep checking the rest
        }
    }
    if (last != null) throw last;
}

Try / catch

try {
    admin = AdminClient.create(props);
} catch (ConfigException e) {
    if (e.getMessage().startsWith("Unknown host in bootstrap.servers")) {
        // DNS failure — could be transient, but the client will not retry this
        // on its own inside parseAndValidateAddresses. Recreate the client AFTER
        // DNS is confirmed working; do not loop tightly.
        scheduleRecheckAfterDnsConfirmed();
    } else throw e;
}

Prevention

Confirm the hostnames resolve from inside the same network namespace/container the client will run in — host DNS and container DNS often differ.
Prefer using IP addresses or stable DNS names for bootstrap; rotating/load-balanced DNS records are fine, but never-resolving names are not.
If running in k8s, use the headless Service DNS name (e.g. kafka-bootstrap.kafka.svc.cluster.local) which resolves to broker pod IPs.
Cache the resolved addresses only as an optimisation — always allow re-resolution, since DNS TTLs expire.

When it happens

Trigger: Calling parseAndValidateAddresses with a host the JVM's configured name service cannot resolve, e.g. 'nonexistent.example.com:9092', a private DNS name on the wrong VPC, or a host spelled differently than the DNS record. Raised during client construction before any network connect.

Common situations: Running a client on a laptop that cannot reach the broker's internal DNS, k8s service name with wrong namespace, broker advertised.listeners pointing at an old hostname, or restrictive /etc/hosts / resolv.conf.

Related errors

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