Cassandraadvanced

Cassandra Repairs

Anti-entropy repair, read repair and hinted handoff — the three mechanisms that converge replicas, and how to schedule the one that matters.

3 min readAdvancedUpdated 31 Jul 2026Edit this page

Apache Cassandra ScyllaDB

Replicas diverge: a node was down, a write timed out, a network blip dropped a message. Three mechanisms bring them back together, and only one of them is complete.

Hinted Handoff

When a coordinator cannot reach a replica, it stores a hint locally and replays it when the replica returns.

hinted_handoff_enabled: true
max_hint_window_in_ms: 10800000     # 3 hours
hinted_handoff_throttle_in_kb: 1024

nodetool statushandoff
nodetool listendpointspendinghints

Read Repair

When a read contacts several replicas and they disagree, the coordinator returns the newest value and writes it back to the stale replicas.

ALTER TABLE shop.events_by_user WITH read_repair = 'BLOCKING';

BLOCKING completes the repair before returning the result; NONE disables it. Note that read repair only fixes data that is read — anything nobody queries stays divergent indefinitely.

Anti-entropy repair

The only mechanism that reconciles everything. Replicas build Merkle trees of their data, compare them, and stream the differing ranges.

# Primary-range repair on one node, one keyspace. Run on every node in turn.
nodetool repair -pr shop
 
# Full repair of a specific table.
nodetool repair -full shop events_by_user
 
# Incremental repair marks repaired SSTables so later runs skip them.
nodetool repair shop

Repair is resource intensive and must be scheduled deliberately

Repair reads all the data being compared, builds Merkle trees, and streams differences. On a large cluster it can take hours per node and adds substantial CPU, disk and network load. Run it during low traffic, one node at a time, and throttle streaming:

nodetool setstreamthroughput 64      # MB/s
nodetool netstats                    # watch progress

Never start repair on several nodes simultaneously in a small cluster.

Repair cadence

For clusters of any size, use a scheduler rather than cron loops: Cassandra Reaper is the common choice, and it handles segmentation, retries, concurrency limits and progress tracking.

Which repair type

Type	Use
`-pr` (primary range)	Routine scheduled repair; each node repairs only the ranges it owns primarily, so a full pass across all nodes covers everything once
`-full`	After a node replacement, after raising the replication factor, or when incremental repair state is suspect
Incremental	Reduces repeat work, but adds complexity around SSTable repaired state; verify it behaves as expected on your version before relying on it

After a node replacement

A replaced node bootstraps its data from replicas, but any range where the replicas themselves disagree stays divergent. Run a full repair on the new node once bootstrap completes, and confirm it finished rather than assuming.