apache/cassandra · error · IllegalStateException

Insufficient read responses: ${readResponses}; need ${sizeOf

Error message

Insufficient read responses: ${readResponses}; need ${sizeOfReadQuorum}

What it means

In PaxosPrepare, once a quorum of permissions is witnessed, a serial (read) request must already hold a read quorum of responses. If not — an internal invariant violation in response accounting — this IllegalStateException is thrown rather than proceeding with an unsafe read decision.

Source

Thrown at src/java/org/apache/cassandra/service/paxos/PaxosPrepare.java:662

                    break;

                case AFTER:
                    if (maybeCheckForLinearizabilityViolation(permitted, from))
                        return;
                    // witnessing future commit doesn't imply have seen prior, so add to refresh list

                case BEFORE:
                    if (needLatest == null)
                        needLatest = new ArrayList<>(participants.sizeOfPoll() - withLatest.size());
                    needLatest.add(from);
            }
        }

        haveQuorumOfPermissions |= withLatest() + needLatest() >= participants.sizeOfConsensusQuorum;
        if (haveQuorumOfPermissions)
        {
            if (request.read != null && readResponses.size() < participants.sizeOfReadQuorum)
                throw new IllegalStateException("Insufficient read responses: " + readResponses + "; need " + participants.sizeOfReadQuorum);

            if (!hasOnlyPromises && !hasProposalStability)
                signalDone(SUPERSEDED);

            // We must be certain to have witnessed a quorum of responses before completing any in-progress proposal
            // else we may complete a stale proposal that did not reach a quorum (and may do so in preference
            // to a different in progress proposal that did reach a quorum).

            // We should also be sure to return any in progress proposal in preference to any incompletely committed
            // earlier commits (since, while we should encounter it next round, any commit that is incomplete in the
            // presence of an incomplete proposal can be ignored, as either the proposal is a re-proposal of the same
            // commit or the commit has already reached a quorum
            else if (hasInProgressProposal())
                signalDone(hasOnlyPromises ? FOUND_INCOMPLETE_ACCEPTED : SUPERSEDED);

            else if (withLatest() >= participants.sizeOfConsensusQuorum)
                signalDone(hasOnlyPromises ? PROMISED : READ_PERMITTED);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Retry the serial operation — this is usually a transient race; log the exception with tracing for diagnosis
Verify cluster health and schema agreement (all nodes same version, no flapping nodes)
If reproducible, gather logs/ccm repro and report as a Cassandra bug (internal invariant violated)
Ensure the read quorum is achievable for the RF and consistency level before issuing serial reads (healthy replicas)

Defensive patterns

Strategy: retry

Validate before calling

// ensure healthy replica set for serial reads before issuing
// nodetool status / system.peers check: live replicas >= RF for the table

Try / catch

try { session.execute(serialRead); }
catch (DriverException e) { /* IllegalStateException from coordinator: retry; if persistent, collect logs and file a bug */ }

Prevention

Keep all replicas healthy during serial-read-heavy workloads
Keep the cluster on a uniform Cassandra version
Enable tracing and retain logs for Paxos invariant violations to aid bug reports

When it happens

Trigger: A serial consensus read whose prepare phase collected enough 'permissions' (promises/quorum) from participants but fewer read responses than participants.sizeOfReadQuorum by the time the quorum of permissions triggers completion — i.e. responses arrived out of order or a read quorum was never satisfied while the permission quorum fired.

Common situations: Node faults/restarts mid-prepare leaving the coordinator with a skewed response mix; races between onResponse callbacks and electorate changes; genuine internal bug triggered by unusual failure/timing patterns during Paxos reads; mixed-version clusters with differing quorum accounting.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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