{"id":"bea99863e3596441","repo":"apache/kafka","slug":"no-resolvable-bootstrap-urls-given-in-bootstrap-se","errorCode":null,"errorMessage":"No resolvable bootstrap urls given in bootstrap.servers","messagePattern":"No resolvable bootstrap urls given in bootstrap\\.servers","errorType":"validation","errorClass":"ConfigException","httpStatus":null,"severity":"critical","filePath":"clients/src/main/java/org/apache/kafka/clients/ClientUtils.java","lineNumber":147,"sourceCode":"        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) {\n        SecurityProtocol securityProtocol = SecurityProtocol.forName(config.getString(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG));\n        String clientSaslMechanism = config.getString(SaslConfigs.SASL_MECHANISM);\n        return ChannelBuilders.clientChannelBuilder(securityProtocol, JaasContext.Type.CLIENT, config, null,\n                clientSaslMechanism, time, logContext);\n    }","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/ClientUtils.java#L129-L165","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nbootstrap.servers=,,\n// after\nbootstrap.servers=broker1:9092,broker2:9092,broker3:9092","handlingStrategy":"validation","validationCode":"// The aggregate failure: every entry either was empty, unresolvable, or\n// skipped. Pre-flight: at least one entry must both parse AND resolve.\nimport java.net.InetAddress;\nimport org.apache.kafka.common.utils.Utils;\n\nstatic List<String> resolvableBootstrap(List<String> raw) throws UnknownHostException {\n    List<String> ok = new ArrayList<>();\n    for (String url : raw) {\n        if (url == null || url.isBlank()) continue;\n        String host = Utils.getHost(url);\n        Integer port = Utils.getPort(url);\n        if (host == null || port == null) continue;\n        try {\n            InetAddress.getAllByName(host);\n            ok.add(url);\n        } catch (UnknownHostException ignored) { /* skip */ }\n    }\n    if (ok.isEmpty())\n        throw new IllegalStateException(\"No bootstrap url in \" + raw + \" is resolvable\");\n    return ok;\n}","typeGuard":null,"tryCatchPattern":"try {\n    client = AdminClient.create(props);\n} catch (ConfigException e) {\n    if (e.getMessage().startsWith(\"No resolvable bootstrap urls\")) {\n        // Every entry failed. Treat as a startup-blocking config fault;\n        // surface to the operator — do NOT silently retry in a loop.\n        failHealthCheckAndStop(e);\n    } else throw e;\n}","preventionTips":["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."],"tags":["config","bootstrap-servers","dns","startup"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}