What causes "Invalid url in bootstrap.servers: {url}" in apache/kafka?

Inspect the exact 'url' value printed in the message; every bootstrap entry must be 'host:port' with a 1-65535 numeric port.

apache/kafka · error · ConfigException

Invalid url in bootstrap.servers: {url}

Error message

Invalid url in bootstrap.servers: {url}

What it means

ConfigException thrown by BootstrapConfiguration.enabled() when one of the supplied bootstrap URLs fails to yield both a host and a port via Utils.getHost/Utils.getPort. This is the lightweight pre-flight validation invoked from ClientUtils.createNetworkClient before any DNS resolution or NetworkClient construction, so malformed bootstrap strings abort client creation early.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/BootstrapConfiguration.java:49

    public final long retryBackoffMs;

    private BootstrapConfiguration(final List<String> bootstrapServers,
                                   final ClientDnsLookup clientDnsLookup,
                                   final long bootstrapResolveTimeoutMs,
                                   final long retryBackoffMs) {
        this.bootstrapServers = bootstrapServers;
        this.clientDnsLookup = clientDnsLookup;
        this.bootstrapResolveTimeoutMs = bootstrapResolveTimeoutMs;
        this.retryBackoffMs = retryBackoffMs;
    }

    public static BootstrapConfiguration enabled(final List<String> bootstrapServers,
                                                 final ClientDnsLookup clientDnsLookup,
                                                 final long bootstrapResolveTimeoutMs,
                                                 final long retryBackoffMs) {
        for (String url : bootstrapServers) {
            if (Utils.getHost(url) == null || Utils.getPort(url) == null)
                throw new ConfigException("Invalid url in " + CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG + ": " + url);
        }
        return new BootstrapConfiguration(bootstrapServers, clientDnsLookup, bootstrapResolveTimeoutMs, retryBackoffMs);
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

Inspect the exact 'url' value printed in the message; every bootstrap entry must be 'host:port' with a 1-65535 numeric port.
Correct the bootstrap.servers value, e.g. 'localhost:9092,kafka2:9092'. For IPv6 use '[::1]:9092'.
Validate the config source (env var / Properties file / Spring placeholder) is not stripping the port or injecting an extra scheme prefix.

Example fix

// before
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "kafka1 kafka2:9092");
// after
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "kafka1:9092,kafka2:9092");

Defensive patterns

Strategy: validation

Validate before calling

// Validate every bootstrap.servers entry BEFORE constructing the client.
// Kafka wants the form host:port (no scheme, no path).
import org.apache.kafka.common.utils.Utils;

static void checkBootstrapServers(List<String> servers) {
    if (servers == null || servers.isEmpty())
        throw new IllegalArgumentException("bootstrap.servers is empty");
    for (String url : servers) {
        String host = Utils.getHost(url);
        Integer port = Utils.getPort(url);
        if (host == null || port == null)
            throw new IllegalArgumentException("Invalid bootstrap url (expect host:port): " + url);
    }
}

// Call this with the same list you will pass as CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG.

Type guard

// Predicate the caller can use to filter/guard before config construction.
static boolean isValidBootstrapUrl(String url) {
    return url != null
        && Utils.getHost(url) != null
        && Utils.getPort(url) != null;
}

// List<String> clean = raw.stream().filter(App::isValidBootstrapUrl).toList();

Try / catch

// Wrap client construction; ConfigException is the failure type.
try {
    try (var admin = AdminClient.create(props)) {
        // ... use admin ...
    }
} catch (org.apache.kafka.common.config.ConfigException e) {
    if (e.getMessage().contains("bootstrap.servers")) {
        log.error("Bad bootstrap.servers config: {}", e.getMessage());
        // surface to operator / fail fast — do NOT retry with the same value.
    } else throw e;
}

Prevention

Source bootstrap.servers from a single validated config object rather than concatenating strings in multiple places.
Reject URLs containing schemes (kafka://), paths, or query strings at config-load time — Kafka accepts only host:port pairs.
Provide at least 2–3 bootstrap servers so that one malformed or unreachable entry does not sink the whole client.
Unit-test the config parser with property/fuzz inputs before deploying.

When it happens

Trigger: Constructing a KafkaProducer/KafkaConsumer/AdminClient/KafkaClient whose bootstrap.servers config contains an entry like 'kafka' (no port), ':9092' (no host), 'localhost:notaport' (non-numeric), or an empty string. Reached via BootstrapConfiguration.enabled(...) inside createNetworkClient.

Common situations: Loading bootstrap.servers from an environment variable or properties file that drops the port, copying a broker URL formatted for a schema registry ('http://host:8081'), IPv6 literals without brackets, or trailing commas that create blank entries.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/6e72102fe5652d05.json. Report an issue: GitHub.