{"id":"9f2455f381311f3c","repo":"apache/kafka","slug":"can-t-resolve-address-address","errorCode":null,"errorMessage":"Can't resolve address: ${address}","messagePattern":"Can't resolve address: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/network/Selector.java","lineNumber":280,"sourceCode":"                immediatelyConnectedKeys.add(key);\n                key.interestOps(0);\n            }\n        } catch (IOException | RuntimeException e) {\n            if (key != null)\n                immediatelyConnectedKeys.remove(key);\n            channels.remove(id);\n            socketChannel.close();\n            throw e;\n        }\n    }\n\n    // Visible to allow test cases to override. In particular, we use this to implement a blocking connect\n    // in order to simulate \"immediately connected\" sockets.\n    protected boolean doConnect(SocketChannel channel, InetSocketAddress address) throws IOException {\n        try {\n            return channel.connect(address);\n        } catch (UnresolvedAddressException e) {\n            throw new IOException(\"Can't resolve address: \" + address, e);\n        }\n    }\n\n    private void configureSocketChannel(SocketChannel socketChannel, int sendBufferSize, int receiveBufferSize)\n            throws IOException {\n        socketChannel.configureBlocking(false);\n        Socket socket = socketChannel.socket();\n        socket.setKeepAlive(true);\n        if (sendBufferSize != Selectable.USE_DEFAULT_BUFFER_SIZE)\n            socket.setSendBufferSize(sendBufferSize);\n        if (receiveBufferSize != Selectable.USE_DEFAULT_BUFFER_SIZE)\n            socket.setReceiveBufferSize(receiveBufferSize);\n        socket.setTcpNoDelay(true);\n    }\n\n    /**\n     * Register the nioSelector with an existing channel\n     * Use this on server-side, when a connection is accepted by a different thread but processed by the Selector","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/network/Selector.java#L262-L298","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["From the client host, run 'getent hosts <broker-host>' / 'nslookup <broker-host>' to confirm DNS resolution; fix the hostname or add a hosts entry.","Correct bootstrap.servers (client) and advertised.listeners (broker) to use a hostname resolvable by every peer that will connect.","If running in Kubernetes/Docker, ensure the service name and namespace resolve inside the client pod/container (check /etc/resolv.conf, CoreDNS, headless service).","Use IP literals only for testing; for production prefer stable FQDNs."],"exampleFix":"# before\nbootstrap.servers=brokr1:9092\n\n# after (typo fixed, FQDN resolvable by clients)\nbootstrap.servers=broker1.example.com:9092","handlingStrategy":"validation","validationCode":"// Resolve the broker hostname BEFORE handing it to Selector.connect().\nString host = bootstrapServers.split(\":\")[0];\nint port = Integer.parseInt(bootstrapServers.split(\":\")[1]);\nInetSocketAddress address;\ntry {\n    address = new InetSocketAddress(host, port);\n} catch (IllegalArgumentException ex) {\n    throw new IllegalArgumentException(\"bad broker address \" + host + \":\" + port, ex);\n}\nif (address.isUnresolved()) {\n    throw new java.net.UnknownHostException(\"Cannot resolve broker host: \" + host);\n}\nselector.connect(nodeId, address, sendBuf, recvBuf);","typeGuard":null,"tryCatchPattern":"try {\n    selector.connect(id, address, sendBufferSize, receiveBufferSize);\n} catch (IOException e) {\n    // Includes \"Can't resolve address\". DNS may be transient: retry with backoff, then fail.\n    log.warn(\"Connect to {} failed: {}\", address, e.getMessage());\n    scheduleReconnectWithBackoff(id, address);\n}","preventionTips":["Pre-resolve broker hostnames at startup so a typo fails fast instead of mid-poll.","Configure reachable DNS or /etc/hosts in the client runtime; in Kubernetes, use the cluster DNS suffix.","Keep bootstrap.servers in sync with the cluster; stale hostnames trigger this on every reconnect.","For transient DNS, retry with exponential backoff; for permanent resolution failure, alert and stop."],"tags":["network","dns","connection","bootstrap"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}