apache/cassandra · critical · IOException

Connection Error

Error message

Connection Error

What it means

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().

Source

Thrown at src/java/org/apache/cassandra/transport/SimpleClient.java:276

                    .option(ChannelOption.TCP_NODELAY, true);

        // Configure the pipeline factory.
        if(encryptionOptions.getEnabled())
        {
            bootstrap.handler(new SecureInitializer(largeMessageThreshold));
        }
        else
        {
            bootstrap.handler(new Initializer(largeMessageThreshold));
        }
        ChannelFuture future = bootstrap.connect(new InetSocketAddress(host, port));

        // Wait until the connection attempt succeeds or fails.
        channel = future.awaitUninterruptibly().channel();
        if (!future.isSuccess())
        {
            bootstrap.group().shutdownGracefully();
            throw new IOException("Connection Error", future.cause());
        }
    }

    public ResultMessage execute(String query, ConsistencyLevel consistency)
    {
        return execute(query, Collections.<ByteBuffer>emptyList(), consistency);
    }

    public ResultMessage execute(String query, List<ByteBuffer> values, ConsistencyLevel consistencyLevel)
    {
        Message.Response msg = execute(new QueryMessage(query, QueryOptions.forInternalCalls(consistencyLevel, values)));
        assert msg instanceof ResultMessage;
        return (ResultMessage)msg;
    }

    public ResultMessage.Prepared prepare(String query)
    {
        Message.Response msg = execute(new PrepareMessage(query, null));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify the node is up and native transport is enabled: nodetool status and check native_transport_port is listening (netstat/ss).
  2. Confirm host and port passed to SimpleClient.connect() are correct and reachable (telnet/nc from the client host).
  3. If using encryption, configure the client's SSL factory (EncryptionOptions) to match the server; check the wrapped future.cause() for the root TLS error.
  4. Check firewalls/security groups and seed/host DNS resolution.

Example fix

// before
SimpleClient client = new SimpleClient(host, port);
client.connect(false);
// after
SimpleClient client = new SimpleClient(host, port);
client.connect(false); // inspect ex.getCause() on IOException
// e.g. server not listening:
// $ nodetool status && ss -ltnp | grep 9042
Defensive patterns

Strategy: try-catch

Validate before calling

// before connecting
Process p = Runtime.getRuntime().exec(new String[]{"/bin/sh","-c","ss -ltn | grep :9042"});
if (p.waitFor() != 0) throw new IllegalStateException("native transport port 9042 not listening");

Try / catch

try { client.connect(false); } catch (IOException e) { throw new RuntimeException("Cannot connect: " + e.getCause(), e); }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/dc9dc92fc46b3ab3. Report an issue: GitHub.