apache/cassandra · error · IllegalArgumentException

Unknown peer requested:

Error message

Unknown peer requested: 

What it means

StreamCoordinator.getHostData looks up the HostStreamingData for a given peer and throws IllegalArgumentException('Unknown peer requested: <peer>') when no session bookkeeping exists for that address. It is reached via getSessionById and updateProgress, meaning a stream progress update or session lookup arrived for a peer this node never registered (or already removed).

Solutions

1. Verify both nodes agree on the peer identity (check whether bind-to-interface/port config causes differing InetAddressAndPort keys).
2. If the session was cancelled, let the remote peer's stream fail and re-run the operation (e.g. re-trigger repair/rebuild) rather than pushing updates.
3. Check cluster version consistency and logs around the time of the error to confirm the session lifecycle; retry streaming after both nodes are stable.

Example fix

// before
coordinator.updateProgress(peer, progress); // peer already removed
// after
if (coordinator.hasSession(peer)) coordinator.updateProgress(peer, progress);

if (!coordinator.peerSessionsKnown(peer)) throw new IllegalStateException("peer session not registered: " + peer);

try { coordinator.updateProgress(peer, progress); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown peer requested")) logger.warn("Dropping late stream update for {}", peer); else throw e; }

When it happens

Trigger: A streaming session was cancelled/finished and its peer data removed, then a late updateProgress/getSessionById arrives for that peer; connecting streaming peers whose sessions were never registered on this coordinator; mixed-version or mismatched address (IP vs IP+port) keys between registration and lookup.

Common situations: Node restarts or session aborts mid-stream while the remote peer keeps sending progress; firewall/NAT setups where the peer address seen at registration differs from the lookup address; recovery attempts against streamed sessions after nodetool admin operations cleaned them.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• A node required to move the data consistently is down
• Can not start range streaming as all candidates
• Can't join the ring because bootstrap hasn't completed.
• Cannot send stream data messages for preview streaming…
• CF was dropped during streaming

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

Appendix: source

Thrown at src/java/org/apache/cassandra/streaming/StreamCoordinator.java:254

        for (OutgoingStream stream: streams)
        {
            if (index % step == 0)
            {
                slice = new ArrayList<>();
                result.add(slice);
            }
            slice.add(stream);
            ++index;
        }
        return result;
    }

    private HostStreamingData getHostData(InetAddressAndPort peer)
    {
        HostStreamingData data = peerSessions.get(peer);

        if (data == null)
            throw new IllegalArgumentException("Unknown peer requested: " + peer);
        return data;
    }

    private HostStreamingData getOrCreateHostData(InetSocketAddress peer)
    {
        HostStreamingData data = peerSessions.get(peer);
        if (data == null)
        {
            data = new HostStreamingData();
            peerSessions.put(peer, data);
        }
        return data;
    }

    public TimeUUID getPendingRepair()
    {
        return pendingRepair;
    }

View on GitHub (pinned to 88fd0f6a0e)