apache/kafka · error · ConfigException

No resolvable bootstrap urls given in bootstrap.servers

Error message

No resolvable bootstrap urls given in bootstrap.servers

What it means

ConfigException from ClientUtils.parseAndValidateAddresses when, after iterating all urls, the resolved addresses list is empty. This means every entry was null/empty, or all entries failed to produce any InetSocketAddress (e.g. all filtered out). Distinct from per-entry errors — this fires when nothing survived the loop at all.

Solutions

  1. Set bootstrap.servers to at least one resolvable host:port.
  2. Strip blanks and trailing commas before constructing the client.
  3. Check the source of the value (env var, config file) is populated.
  4. If using clientDnsLookup=use_all_dns_addresses, ensure at least one host has an A/AAAA record.

Example fix

# before
bootstrap.servers=   
# after
bootstrap.servers=broker1:9092,broker2:9092
Defensive patterns

Strategy: validation

Validate before calling

List<String> effective = urls.stream().filter(u -> u != null && !u.trim().isEmpty()).toList();
if (effective.isEmpty()) throw new IllegalArgumentException("bootstrap.servers has no non-empty entries");

Try / catch

try { ClientUtils.parseAndValidateAddresses(urls, dns); } catch (ConfigException e) { if (e.message.contains("No resolvable bootstrap urls")) { /* populate bootstrap.servers */ } else throw e; }

Prevention

When it happens

Trigger: addresses.isEmpty() at line 141 after the for loop. Triggered when the bootstrap.servers list contains only blank/null entries, or when clientDnsLookup filtering removed every address.

Common situations: bootstrap.servers is empty or whitespace-only; value comes from an unset environment variable; trailing comma yields a single blank entry; every entry was filtered by a custom clientDnsLookup mode.

Related errors

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

Appendix: source

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

        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) {
        SecurityProtocol securityProtocol = SecurityProtocol.forName(config.getString(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG));
        String clientSaslMechanism = config.getString(SaslConfigs.SASL_MECHANISM);
        return ChannelBuilders.clientChannelBuilder(securityProtocol, JaasContext.Type.CLIENT, config, null,
                clientSaslMechanism, time, logContext);
    }

View on GitHub (pinned to 996fb4585a)