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

Check the 'url' in the message and replace the port token with a decimal integer in [0,65535].

apache/kafka · error · ConfigException

Invalid port in bootstrap.servers: {url}

Error message

Invalid port in bootstrap.servers: {url}

What it means

ConfigException thrown when the port token of a bootstrap entry cannot be parsed as an integer — Integer.parseInt raises IllegalArgumentException inside the port extraction, which ClientUtils.parseAndValidateAddresses catches and re-wraps as this ConfigException. It indicates the host was present but the port was malformed (non-numeric or out of integer range).

Source

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

    public static List<InetSocketAddress> parseAndValidateAddresses(List<String> urls, String clientDnsLookupConfig) {
        return parseAndValidateAddresses(urls, ClientDnsLookup.forConfig(clientDnsLookupConfig));
    }

    public static List<InetSocketAddress> parseAndValidateAddresses(List<String> urls, ClientDnsLookup clientDnsLookup) {
        List<InetSocketAddress> addresses = new ArrayList<>();
        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.

View on GitHub (pinned to c31c9215e1)

Solutions

Check the 'url' in the message and replace the port token with a decimal integer in [0,65535].
If the port comes from an env var, ensure the variable holds digits only (no protocol suffix, no quotes).
Re-run the client after correcting bootstrap.servers; no restart of the broker is needed.

Example fix

// before
bootstrap.servers=broker1:NINETY_TWO
// after
bootstrap.servers=broker1:9092

Defensive patterns

Strategy: validation

Validate before calling

// The port portion fails Integer.parse (non-numeric, out of range, or missing).
// Validate explicitly with the legal TCP range:
static void checkPorts(List<String> servers) {
    for (String url : servers) {
        Integer port = Utils.getPort(url);          // null if unparsable
        if (port == null || port < 1 || port > 65535)
            throw new IllegalArgumentException(
                "Invalid port in bootstrap.servers: " + url);
    }
}

Type guard

static boolean hasValidPort(String url) {
    Integer p = Utils.getPort(url);
    return p != null && p >= 1 && p <= 65535;
}

Try / catch

try {
    consumer = new KafkaConsumer<>(props);
} catch (ConfigException e) {
    if (e.getMessage().startsWith("Invalid port in bootstrap.servers")) {
        // e.g. "localhost:notANumber" or "localhost:99999"
        alertOps("Malformed port in bootstrap.servers: " + e.getMessage());
        throw e;            // unrecoverable with current config
    }
    throw e;
}

Prevention

Use the canonical Kafka port 9092 unless you have an explicit reason not to; resist templating the port from untrusted input.
Coerce ports through Integer.parseInt with a 1..65535 range check at the config boundary — never pass a raw String straight through.
Beware IPv6 literals: enclose the host in brackets, e.g. [2001:db8::1]:9092, otherwise the port parser will mis-split.
Add a config-lint step in deployment that rejects any bootstrap url whose port substring is non-numeric.

When it happens

Trigger: A bootstrap entry such as 'host:ninety-two', 'host:99999999999', or 'host:' where the port substring is not a valid int. Triggered by the same client constructors that exercise parseAndValidateAddresses.

Common situations: Using a service-name placeholder that leaks a non-numeric value, copy-pasting an HTTPS-style port like 'host:https', or a YAML/env interpolation that injects a labelled value ('9092/tcp').

Related errors

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