apache/kafka · error · ConfigException

Unknown host in bootstrap.servers: {}

Error message

Unknown host in bootstrap.servers: {}

What it means

ConfigException from ClientUtils.parseAndValidateAddresses when resolveAddress throws UnknownHostException for a parsed host:port — the host could not be resolved to any InetSocketAddress under the configured ClientDnsLookup mode. This fires after host/port parsing succeeded, so the URL is well-formed but the DNS lookup failed.

Source

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

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

Solutions

  1. Verify the hostname resolves: nslookup <host> or dig <host> from the client host.
  2. Correct typos in bootstrap.servers.
  3. If DNS is not ready at startup, delay client construction or retry; ensure the hostname is registered before the client starts.
  4. On Kubernetes/cloud, use the service DNS name and confirm the service exists.

Example fix

// before
bootstrap.servers=broker1.prod:9092   // typo / not registered
// after
bootstrap.servers=broker1.kafka.svc.cluster.local:9092
Defensive patterns

Strategy: validation

Validate before calling

// Resolve hostnames up front so the error is clearer than the wrapped ConfigException
for (String url : urls) {
  String host = Utils.getHost(url);
  if (host != null) InetAddress.getAllByName(host); // throws UnknownHostException early
}

Try / catch

try { ClientUtils.parseAndValidateAddresses(urls, dns); } catch (ConfigException e) { if (e.message.contains('Unknown host in bootstrap')) { /* DNS/hostname issue */ } else throw e; }

Prevention

When it happens

Trigger: resolveAddress(url, host, port, clientDnsLookup) throws UnknownHostException, caught at line 136, rethrown as ConfigException("Unknown host in bootstrap.servers: <url>"). Triggered by a non-existent hostname, a typo, or DNS not yet available at construction time.

Common situations: Wrong/typo broker hostname; broker not yet registered in DNS during container/cloud startup; VPN split-tunnel hiding the broker; clientDnsLookup=use_all_dns_addresses with a partially-resolvable name.

Related errors

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