{"record":{"id":"dc2d6f39fb457ea8","repo":"apache/kafka","slug":"unknown-host-in-bootstrap-servers","errorCode":null,"errorMessage":"Unknown host in bootstrap.servers: {}","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":136,"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":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/ClientUtils.java#L118-L154","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the hostname resolves: nslookup <host> or dig <host> from the client host.","Correct typos in bootstrap.servers.","If DNS is not ready at startup, delay client construction or retry; ensure the hostname is registered before the client starts.","On Kubernetes/cloud, use the service DNS name and confirm the service exists."],"exampleFix":"// before\nbootstrap.servers=broker1.prod:9092   // typo / not registered\n// after\nbootstrap.servers=broker1.kafka.svc.cluster.local:9092","handlingStrategy":"validation","validationCode":"// Resolve hostnames up front so the error is clearer than the wrapped ConfigException\nfor (String url : urls) {\n  String host = Utils.getHost(url);\n  if (host != null) InetAddress.getAllByName(host); // throws UnknownHostException early\n}","typeGuard":null,"tryCatchPattern":"try { ClientUtils.parseAndValidateAddresses(urls, dns); } catch (ConfigException e) { if (e.message.contains('Unknown host in bootstrap')) { /* DNS/hostname issue */ } else throw e; }","preventionTips":["Verify hostnames resolve from the client host before starting the client.","Use fully-qualified service DNS names on Kubernetes/cloud.","Delay client construction until DNS is available during startup."],"tags":["kafka-client","config","bootstrap","dns","network"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}