apache/cassandra · error · RuntimeException

[Stream # ] Cannot receive files for preview session

Error message

[Stream #%s] Cannot receive files for preview session

What it means

Preview streaming sessions validate consistency without transferring files. StreamSession.receive() throws this RuntimeException if an IncomingStreamMessage (file data) arrives for a session marked as preview, since preview sessions must never carry data.

Solutions

  1. Verify both ends start the session with the same preview/for-preview flag; fix the initiating repair command (repair type mismatch).
  2. Ensure mixed-version clusters all support and agree on preview streaming semantics.
  3. If data transfer is intended, run a normal repair/rebuild instead of a preview session.
  4. Check StreamResultFuture/session creation code for incorrectly set preview parents or request sessions.

Example fix

// before
session.receive(incomingStreamMessage); // preview session -> throws
// after
if (!session.isPreview()) {
    session.receive(incomingStreamMessage);
} else {
    logger.warn("Rejecting file data for preview session {}", session.planId());
}
Defensive patterns

Strategy: validation

Validate before calling

if (session.isPreview()) { /* refuse to send IncomingStreamMessage */ }

Try / catch

try { session.receive(msg); } catch (RuntimeException e) { if (e.getMessage().contains("preview session")) { logger.warn("Data for preview session, aborting"); session.closeSession(State.Type.FAILED); } else { throw e; } }

Prevention

When it happens

Trigger: Calling StreamSession.receive(IncomingStreamMessage) on a session where isPreview() is true — the peer streamed file data to a node running a preview (validation-only) session.

Common situations: Sender configured a real streaming session while the receiver runs a preview session (mismatched repair parameters, e.g. incremental repair with preview on one side); mixed-version clusters mishandling preview flag propagation.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/streaming/StreamSession.java:1087

        // schedule timeout for receiving ACK
        StreamTransferTask task = transfers.get(message.header.tableId);
        if (task != null)
        {
            task.scheduleTimeout(message.header.sequenceNumber, DatabaseDescriptor.getStreamTransferTaskTimeout().toMilliseconds(), TimeUnit.MILLISECONDS);
        }
    }

    /**
     * Call back after receiving a stream.
     *
     * @param message received stream
     */
    public void receive(IncomingStreamMessage message)
    {
        if (isPreview())
        {
            throw new RuntimeException(String.format("[Stream #%s] Cannot receive files for preview session", planId()));
        }

        long headerSize = message.stream.getSize();
        StreamingMetrics.totalIncomingBytes.inc(headerSize);
        metrics.incomingBytes.inc(headerSize);
        // send back file received message
        sendControlMessage(new ReceivedMessage(message.header.tableId, message.header.sequenceNumber)).syncUninterruptibly();
        StreamHook.instance.reportIncomingStream(message.header.tableId, message.stream, this, message.header.sequenceNumber);
        long receivedStartNanos = nanoTime();
        try
        {
            receivers.get(message.header.tableId).received(message.stream);
        }
        finally
        {
            long latencyNanos = nanoTime() - receivedStartNanos;
            metrics.incomingProcessTime.update(latencyNanos, TimeUnit.NANOSECONDS);
            long latencyMs = TimeUnit.NANOSECONDS.toMillis(latencyNanos);

View on GitHub (pinned to 88fd0f6a0e)