apache/cassandra · critical · IOException

failed to connect to %s for streaming data

Error message

failed to connect to %s for streaming data

What it means

NettyStreamingConnectionFactory.connect() establishes the outbound streaming data connection, retrying only when the failure is SSL-related. When retries are exhausted (or the failure is not SSL-related), it wraps the last cause in an IOException: 'failed to connect to <peer> for streaming data'.

Source

Thrown at src/java/org/apache/cassandra/streaming/async/NettyStreamingConnectionFactory.java:86

                {
                    Channel channel = result.getNow().success().channel;
                    NettyStreamingChannel streamingChannel = new NettyStreamingChannel(channel, kind);
                    if (kind == StreamingChannel.Kind.CONTROL)
                    {
                        ChannelPipeline pipeline = channel.pipeline();
                        pipeline.addLast("stream", streamingChannel);
                    }
                    return streamingChannel;
                }
                cause = result.cause();
            }
            if (!isSSLError(cause))
            {
                // Fallback only when the error is SSL related, otherwise retries are exhausted, so fail
                break;
            }
        }
        throw new IOException("failed to connect to " + template.to + " for streaming data", cause);
    }

    @Override
    public StreamingChannel create(InetSocketAddress to, int messagingVersion, StreamingChannel.Kind kind) throws IOException
    {
        return connect(new OutboundConnectionSettings(getByAddress(to)), messagingVersion, kind);
    }

    @Override
    public StreamingChannel create(InetSocketAddress to,
                                   InetSocketAddress preferred,
                                   int messagingVersion,
                                   StreamingChannel.Kind kind) throws IOException
    {
        return connect(new OutboundConnectionSettings(getByAddress(to), getByAddress(preferred)), messagingVersion, kind);
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the target node is up and the streaming port is reachable: nodetool status, then nc/telnet to peer host and streaming port from the source node.
2. Check firewall/SecurityGroup rules for the storage/streaming port (7000 or ssl_storage_port 7001) between the nodes.
3. Review address configuration (broadcast_address, broadcast_rpc_address, prefer_local, endpoint snitch) so the resolved peer address is correct.
4. If TLS is enabled, validate keystore/truststore paths and passwords in cassandra.yaml on both ends.
5. Retry once the peer recovers; streaming sessions will fail and the operation (repair/rebuild) must be rerun.

Example fix

// before
// connect() fails: peer unreachable on streaming port
// after
// verify reachability before starting the stream
if (!reachable(peer, streamingPort, 5000)) {
    throw new IOException("Peer " + peer + " not reachable on streaming port " + streamingPort);
}

try (Socket s = new Socket()) { s.connect(new InetSocketAddress(peer, streamingPort), 5000); } catch (IOException e) { /* abort before streaming */ }

try { channel = factory.create(peerAddr, version, Kind.DATA); } catch (IOException e) { logger.error("Streaming connect to {} failed: {}", peerAddr, e.getCause()); throw e; } // inspect e.getCause() for ConnectException vs SSLException

When it happens

Trigger: connect(OutboundConnectionSettings, messagingVersion, kind) invoked via create() when the TCP connection to the peer's streaming port fails — peer down, wrong IP, firewall blocking the streaming port (7000 family / ssl storage port), TLS handshake failure after exhausting SSL fallback retries.

Common situations: Target node down or decommissioned during repair/rebuild; firewalled streaming port between datacenters; incorrect broadcast/Preferred IP configuration; missing or mismatched SSL keystore/truststore for encrypted streaming.

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

• The channel this output stream was writing to has been close
• This output stream is in an unsafe state after an asynchrono
• Can not start range streaming as all candidates (%s) are dow
• Failed to connect to JMX
• Connection Error

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