apache/kafka · error · IOException

Can't resolve address: ${address}

Error message

Can't resolve address: ${address}

What it means

Thrown by Selector.doConnect as an IOException when SocketChannel.connect raises java.nio.channels.UnresolvedAddressException. The Kafka client wraps it so callers see a clearer 'Can't resolve address' message with the offending InetSocketAddress. It indicates the hostname in the bootstrap.servers / advertised.listeners could not be resolved to an IP at connect time — distinct from a refused connection, this is a DNS/lookup failure.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/network/Selector.java:280

                immediatelyConnectedKeys.add(key);
                key.interestOps(0);
            }
        } catch (IOException | RuntimeException e) {
            if (key != null)
                immediatelyConnectedKeys.remove(key);
            channels.remove(id);
            socketChannel.close();
            throw e;
        }
    }

    // Visible to allow test cases to override. In particular, we use this to implement a blocking connect
    // in order to simulate "immediately connected" sockets.
    protected boolean doConnect(SocketChannel channel, InetSocketAddress address) throws IOException {
        try {
            return channel.connect(address);
        } catch (UnresolvedAddressException e) {
            throw new IOException("Can't resolve address: " + address, e);
        }
    }

    private void configureSocketChannel(SocketChannel socketChannel, int sendBufferSize, int receiveBufferSize)
            throws IOException {
        socketChannel.configureBlocking(false);
        Socket socket = socketChannel.socket();
        socket.setKeepAlive(true);
        if (sendBufferSize != Selectable.USE_DEFAULT_BUFFER_SIZE)
            socket.setSendBufferSize(sendBufferSize);
        if (receiveBufferSize != Selectable.USE_DEFAULT_BUFFER_SIZE)
            socket.setReceiveBufferSize(receiveBufferSize);
        socket.setTcpNoDelay(true);
    }

    /**
     * Register the nioSelector with an existing channel
     * Use this on server-side, when a connection is accepted by a different thread but processed by the Selector

View on GitHub (pinned to c31c9215e1)

Solutions

1. From the client host, run 'getent hosts <broker-host>' / 'nslookup <broker-host>' to confirm DNS resolution; fix the hostname or add a hosts entry.
2. Correct bootstrap.servers (client) and advertised.listeners (broker) to use a hostname resolvable by every peer that will connect.
3. If running in Kubernetes/Docker, ensure the service name and namespace resolve inside the client pod/container (check /etc/resolv.conf, CoreDNS, headless service).
4. Use IP literals only for testing; for production prefer stable FQDNs.

Example fix

# before
bootstrap.servers=brokr1:9092

# after (typo fixed, FQDN resolvable by clients)
bootstrap.servers=broker1.example.com:9092

// Resolve the broker hostname BEFORE handing it to Selector.connect().
String host = bootstrapServers.split(":")[0];
int port = Integer.parseInt(bootstrapServers.split(":")[1]);
InetSocketAddress address;
try {
    address = new InetSocketAddress(host, port);
} catch (IllegalArgumentException ex) {
    throw new IllegalArgumentException("bad broker address " + host + ":" + port, ex);
}
if (address.isUnresolved()) {
    throw new java.net.UnknownHostException("Cannot resolve broker host: " + host);
}
selector.connect(nodeId, address, sendBuf, recvBuf);

try {
    selector.connect(id, address, sendBufferSize, receiveBufferSize);
} catch (IOException e) {
    // Includes "Can't resolve address". DNS may be transient: retry with backoff, then fail.
    log.warn("Connect to {} failed: {}", address, e.getMessage());
    scheduleReconnectWithBackoff(id, address);
}

When it happens

Trigger: Calling Selector.connect(id, address, ...) (via NetworkClient -> initiateConnect) with an InetSocketAddress whose host has no DNS A/AAAA record; happens at producer/consumer/admin startup, broker inter-broker connects, or controller connections.

Common situations: Typo in bootstrap.servers hostname; DNS server unreachable from the broker/client container; short hostname used where FQDN is required (or vice-versa across Kerberos/TLS); advertised.listeners set to a hostname the client cannot resolve; /etc/hosts or /etc/resolv.conf misconfigured in a container.

Related errors

• Unknown host in bootstrap.servers: {url}
• Connection to {node} failed.
• Failed to update metadata after {timeoutMs} ms.
• Invalid receive (size = ${receiveSize})
• No resolvable bootstrap urls given in bootstrap.servers

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