{"record":{"id":"dc9dc92fc46b3ab3","repo":"apache/cassandra","slug":"connection-error","errorCode":null,"errorMessage":"Connection Error","messagePattern":"Connection Error","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/transport/SimpleClient.java","lineNumber":276,"sourceCode":"                    .option(ChannelOption.TCP_NODELAY, true);\n\n        // Configure the pipeline factory.\n        if(encryptionOptions.getEnabled())\n        {\n            bootstrap.handler(new SecureInitializer(largeMessageThreshold));\n        }\n        else\n        {\n            bootstrap.handler(new Initializer(largeMessageThreshold));\n        }\n        ChannelFuture future = bootstrap.connect(new InetSocketAddress(host, port));\n\n        // Wait until the connection attempt succeeds or fails.\n        channel = future.awaitUninterruptibly().channel();\n        if (!future.isSuccess())\n        {\n            bootstrap.group().shutdownGracefully();\n            throw new IOException(\"Connection Error\", future.cause());\n        }\n    }\n\n    public ResultMessage execute(String query, ConsistencyLevel consistency)\n    {\n        return execute(query, Collections.<ByteBuffer>emptyList(), consistency);\n    }\n\n    public ResultMessage execute(String query, List<ByteBuffer> values, ConsistencyLevel consistencyLevel)\n    {\n        Message.Response msg = execute(new QueryMessage(query, QueryOptions.forInternalCalls(consistencyLevel, values)));\n        assert msg instanceof ResultMessage;\n        return (ResultMessage)msg;\n    }\n\n    public ResultMessage.Prepared prepare(String query)\n    {\n        Message.Response msg = execute(new PrepareMessage(query, null));","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/transport/SimpleClient.java#L258-L294","documentation":"SimpleClient.connect() fails to establish the Netty channel to the Cassandra native-protocol port and wraps the underlying connect failure in an IOException before shutting down the event loop group. It means the TCP connection to the node could not be completed, and the original cause (unreachable host, refused port, TLS failure) is available via getCause().","triggerScenarios":"Calling SimpleClient.connect(host, port) (or connect with a custom initializer) when the bootstrap future fails: host unreachable, native transport port closed (storage_port/native_transport_port not listening), TLS handshake rejection, or DNS resolution failure.","commonSituations":"Cassandra not running or native transport disabled (native_transport_enabled: false); wrong port; firewall/security-group blocking; connecting to the TLS port without SSL configured (or vice versa); node still bootstrapping.","solutions":["Verify the node is up and native transport is enabled: nodetool status and check native_transport_port is listening (netstat/ss).","Confirm host and port passed to SimpleClient.connect() are correct and reachable (telnet/nc from the client host).","If using encryption, configure the client's SSL factory (EncryptionOptions) to match the server; check the wrapped future.cause() for the root TLS error.","Check firewalls/security groups and seed/host DNS resolution."],"exampleFix":"// before\nSimpleClient client = new SimpleClient(host, port);\nclient.connect(false);\n// after\nSimpleClient client = new SimpleClient(host, port);\nclient.connect(false); // inspect ex.getCause() on IOException\n// e.g. server not listening:\n// $ nodetool status && ss -ltnp | grep 9042","handlingStrategy":"try-catch","validationCode":"// before connecting\nProcess p = Runtime.getRuntime().exec(new String[]{\"/bin/sh\",\"-c\",\"ss -ltn | grep :9042\"});\nif (p.waitFor() != 0) throw new IllegalStateException(\"native transport port 9042 not listening\");","typeGuard":null,"tryCatchPattern":"try { client.connect(false); } catch (IOException e) { throw new RuntimeException(\"Cannot connect: \" + e.getCause(), e); }","preventionTips":["Check nodetool status and that the native port is listening before connecting","Match SSL/encryption config between client and server","Test port reachability with nc/telnet from the client host"],"tags":["network","connection","native-protocol","netty"],"backgroundTag":"connection-refused","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}