{"id":"f8ab2d549a085194","repo":"apache/kafka","slug":"unknown-host-in-bootstrap-servers-url","errorCode":null,"errorMessage":"Unknown host in bootstrap.servers: {url}","messagePattern":"Unknown host in bootstrap\\.servers: (.+?)","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/ClientUtils.java","lineNumber":142,"sourceCode":"        return parseAndValidateAddresses(urls, ClientDnsLookup.forConfig(clientDnsLookupConfig));\n    }\n\n    public static List<InetSocketAddress> parseAndValidateAddresses(List<String> urls, ClientDnsLookup clientDnsLookup) {\n        List<InetSocketAddress> addresses = new ArrayList<>();\n        for (String url : urls) {\n            if (url != null && !url.isEmpty()) {\n                try {\n                    String host = getHost(url);\n                    Integer port = getPort(url);\n                    if (host == null || port == null)\n                        throw new ConfigException(\"Invalid url in \" + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + \": \" + url);\n\n                    addresses.addAll(resolveAddress(url, host, port, clientDnsLookup));\n\n                } catch (IllegalArgumentException e) {\n                    throw new ConfigException(\"Invalid port in \" + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + \": \" + url);\n                } catch (UnknownHostException e) {\n                    throw new ConfigException(\"Unknown host in \" + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + \": \" + url);\n                }\n            }\n        }\n        if (addresses.isEmpty())\n            throw new ConfigException(\"No resolvable bootstrap urls given in \" + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG);\n        return addresses;\n    }\n\n    /**\n     * Create a new channel builder from the provided configuration.\n     *\n     * @param config client configs\n     * @param time the time implementation\n     * @param logContext the logging context\n     *\n     * @return configured ChannelBuilder based on the configs.\n     */\n    public static ChannelBuilder createChannelBuilder(AbstractConfig config, Time time, LogContext logContext) {","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/ClientUtils.java#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nbootstrap.servers=broker.internal:9092   // not resolvable from client host\n// after\nbootstrap.servers=10.0.0.5:9092            // reachable IP, or fix DNS to resolve broker.internal","handlingStrategy":"validation","validationCode":"// Resolve the host up front so an unresolvable name is caught at startup,\n// not later inside ClientUtils. NOTE: DNS may be transient — if resolution\n// fails, retry once after a short backoff before declaring the config bad.\nimport java.net.InetAddress;\n\nstatic void checkResolvable(List<String> servers) throws UnknownHostException {\n    UnknownHostException last = null;\n    for (String url : servers) {\n        String host = Utils.getHost(url);\n        if (host == null) continue;\n        try {\n            InetAddress.getAllByName(host);\n        } catch (UnknownHostException e) {\n            last = e;        // collect but keep checking the rest\n        }\n    }\n    if (last != null) throw last;\n}","typeGuard":null,"tryCatchPattern":"try {\n    admin = AdminClient.create(props);\n} catch (ConfigException e) {\n    if (e.getMessage().startsWith(\"Unknown host in bootstrap.servers\")) {\n        // DNS failure — could be transient, but the client will not retry this\n        // on its own inside parseAndValidateAddresses. Recreate the client AFTER\n        // DNS is confirmed working; do not loop tightly.\n        scheduleRecheckAfterDnsConfirmed();\n    } else throw e;\n}","preventionTips":["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."],"tags":["config","bootstrap-servers","dns","network"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}