{"record":{"id":"d8d13fd86778842c","repo":"apache/kafka","slug":"connection-to-node-failed","errorCode":null,"errorMessage":"Connection to {node} failed.","messagePattern":"Connection to (.+?) failed\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/NetworkClientUtils.java","lineNumber":71,"sourceCode":"     * connection timeoutMs, it is possible for this method to raise an `IOException` for a previous connection which\n     * has recently disconnected. If authentication to the node fails, an `AuthenticationException` is thrown.\n     *\n     * This method is useful for implementing blocking behaviour on top of the non-blocking `NetworkClient`, use it with\n     * care.\n     */\n    public static boolean awaitReady(KafkaClient client, Node node, Time time, long timeoutMs) throws IOException {\n        if (timeoutMs < 0) {\n            throw new IllegalArgumentException(\"Timeout needs to be greater than 0\");\n        }\n        long startTime = time.milliseconds();\n\n        if (isReady(client, node, startTime) ||  client.ready(node, startTime))\n            return true;\n\n        long attemptStartTime = time.milliseconds();\n        while (!client.isReady(node, attemptStartTime) && attemptStartTime - startTime < timeoutMs) {\n            if (client.connectionFailed(node)) {\n                throw new IOException(\"Connection to \" + node + \" failed.\");\n            }\n            long pollTimeout = timeoutMs - (attemptStartTime - startTime); // initialize in this order to avoid overflow\n\n            // If the network client is waiting to send data for some reason (eg. throttling or retry backoff),\n            // polling longer than that is potentially dangerous as the producer will not attempt to send\n            // any pending requests.\n            long waitingTime = client.pollDelayMs(node, startTime);\n            if (waitingTime > 0 && pollTimeout > waitingTime) {\n                // Block only until the next-scheduled time that it's okay to send data to the producer,\n                // wake up, and try again. This is the way.\n                pollTimeout = waitingTime;\n            }\n\n            client.poll(pollTimeout, attemptStartTime);\n            if (client.authenticationException(node) != null)\n                throw client.authenticationException(node);\n            attemptStartTime = time.milliseconds();\n        }","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/kafka/blob/996fb4585aa1bcc8980b0e1b8d6b168b986cd979/clients/src/main/java/org/apache/kafka/clients/NetworkClientUtils.java#L53-L89","documentation":"Thrown by NetworkClientUtils.awaitReady() inside the polling loop when client.connectionFailed(node) returns true. This means the connection attempt to the given node failed (e.g. authentication failure, connection refused, or an error during the handshake), so waiting further is pointless.","triggerScenarios":"During the awaitReady loop, after polling, connectionFailed(node) is true — the node's connection entered a failed state. Distinct from a timeout; this is an explicit connection-level failure.","commonSituations":"Broker is down or refusing connections, SASL/SSL authentication failure, firewall dropping the connection, wrong port, or the node id resolving to a dead broker. Also triggered by authentication exceptions surfaced through the connection state.","solutions":["Verify the broker at the given node host:port is running and reachable.","Check authentication (SASL/SSL) credentials and configuration.","Inspect network/firewall rules between the client and broker.","Review broker logs for the refused or failed connection attempt."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    NetworkClientUtils.awaitReady(client, node, time, timeoutMs);\n} catch (IOException e) {\n    // connection failed: inspect auth config and broker reachability\n}","preventionTips":["Pre-flight a connectivity/auth check before relying on awaitReady.","Log the node identity on failure to pinpoint the bad broker.","Distinguish connection-failed IOException from timeout (awaitReady returns false)."],"tags":["network","connection","authentication"],"backgroundTag":null,"analyzedSha":"996fb4585aa1bcc8980b0e1b8d6b168b986cd979","analyzedAt":"2026-08-11T22:03:28.655Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}