apache/cassandra · error · StreamException

Stream failed: \nSession peer <peer> <failureReason> (per fa

Error message

Stream failed: \nSession peer <peer> <failureReason> (per failed session)

What it means

StreamResultFuture.maybeComplete() finalizes a streaming plan. If any session failed (info.isFailed()), it builds a summary listing each failed peer and its failureReason, logs it as a warning ('[Stream #id] Stream failed: ...'), and tryFailure(new StreamException(finalState, message)). The overall stream future completes exceptionally with this StreamException.

Source

Thrown at src/java/org/apache/cassandra/streaming/StreamResultFuture.java:252

    }

    private synchronized void maybeComplete()
    {
        if (finishedAllSessions())
        {
            StreamState finalState = getCurrentState();
            if (finalState.hasFailedSession())
            {
                StringBuilder stringBuilder = new StringBuilder();
                stringBuilder.append("Stream failed: ");
                for (SessionInfo info : finalState.sessions())
                {
                    if (info.isFailed())
                        stringBuilder.append("\nSession peer ").append(info.peer).append(' ').append(info.failureReason);
                }
                String message = stringBuilder.toString();
                logger.warn("[Stream #{}] {}", planId, message);
                tryFailure(new StreamException(finalState, message));
            }
            else if (finalState.hasAbortedSession())
            {
                logger.info("[Stream #{}] Stream aborted", planId);
                trySuccess(finalState);
            }
            else
            {
                logger.info("[Stream #{}] All sessions completed", planId);
                trySuccess(finalState);
            }
        }
    }

    public StreamSession getSession(InetAddressAndPort peer, int sessionIndex)
    {
        return coordinator.getSessionById(peer, sessionIndex);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Read the per-peer failureReason lines in the message/log to find the root cause (e.g. StreamException from the peer)
2. Verify connectivity between the nodes and re-run repair/bootstrap (nodetool repair, or retry the operation)
3. Check the receiving node's logs and disk space; fix any underlying I/O issue
4. Increase streaming timeouts/throughput settings if the failure was a slow-link timeout

// before streaming, verify peers reachable
for (InetAddressAndPort peer : peers)
    if (!isReachable(peer)) throw new IllegalStateException("Peer down, streaming would fail: " + peer);

try {
    streamFuture.get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof StreamException se) {
        // message lists each failed peer + failureReason
        se.getMessage().lines().filter(l -> l.contains("Session peer"))
          .forEach(l -> logger.error("Stream failure: {}", l));
        scheduleStreamRetry();
    }
}

When it happens

Trigger: Any streaming session in the plan ends in FAILED state — e.g. peer node down mid-stream, network interruption, disk errors on receiver, or range movement during bootstrap/repair/decommission.

Common situations: Node restarts during bootstrap/repair; network partitions or timeouts between datacenters; misconfigured streaming_socket settings; disk full on the receiving node.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Unable to find sufficient sources for streaming range " + tr
• Unable to find sufficient sources for streaming range " + ra
• Keyspace is already added to fetch map
• Unable to find sufficient sources for streaming range in ke
• Discovered existing bootstrap data and %s is not configured;

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