Repair Options Reference¶
This page provides detailed explanations of all repair command options, including visual diagrams showing how each option affects repair behavior.
Command Syntax¶
nodetool repair [options] [keyspace [table ...]]
Scope Options¶
-pr, --partitioner-range (Primary Range)¶
Repairs only the token ranges for which this node is the primary owner.
Usage:
# Recommended for routine maintenance
nodetool repair -pr my_keyspace
When to use: - Regular scheduled repairs - Running repair on every node in sequence - Minimizing redundant work
When NOT to use: - Single-node recovery scenarios - Verifying specific replica consistency
-full (Full Repair)¶
Forces full repair instead of incremental repair, validating all data regardless of repair status.
Usage:
# Full repair of all data
nodetool repair -full my_keyspace
# Combine with -pr for full primary-range repair
nodetool repair -full -pr my_keyspace
When to use: - After node replacement or rebuild - After data corruption recovery - When incremental repair state is suspect - Before major version upgrades
-st, -et (Subrange Repair)¶
Repairs only a specific token range, enabling parallel repair operations or targeted recovery.
Usage:
# Repair specific token range
nodetool repair -st -9223372036854775808 -et -3074457345618258603 my_keyspace
# Get token ranges for a node
nodetool describering my_keyspace
Use cases: - Parallel repair across multiple sessions - Targeted repair of specific token ranges - Recovery of specific data segments
Parallelism Options¶
Parallel (Default) vs -seq, --sequential¶
Controls whether replicas validate data simultaneously or one at a time. Parallel is the default in Cassandra 4.0+. There is no --parallel flag; parallel mode is the default behavior.
Usage:
# Sequential (lower impact, slower)
nodetool repair -pr -seq my_keyspace
# Parallel (default - faster, higher resource usage)
nodetool repair -pr my_keyspace
| Aspect | Sequential (-seq) |
Parallel (default) |
|---|---|---|
| Default (4.0+) | No | Yes |
| Duration | Longer | Shorter |
| Resource usage | Lower | Higher |
| Network impact | Distributed over time | Concentrated |
| Production safety | Higher | Lower |
| Recommended for | Production hours | Off-peak maintenance |
-dcpar, --dc-parallel¶
A middle ground between fully sequential and fully parallel repair.
The problem -dcpar solves:
-seq(sequential): Safe but slow—only one replica builds its Merkle tree at a time across the entire cluster--parallel: Fast but resource-intensive—all replicas build Merkle trees simultaneously, which can overwhelm nodes if many ranges are repairing at once-dcpar: Balances both—allows parallelism across datacenters while limiting load within each datacenter
How it works:
During Merkle tree validation, each replica must read its data to build the tree. This is I/O and CPU intensive. With -dcpar:
- Within each datacenter, only one replica validates at a time (sequential)
- Across datacenters, validation happens in parallel
This means if a token range has replicas in DC1 and DC2, both datacenters can validate simultaneously, but each DC only has one replica active at a time.
Example: 2 DCs, RF=2 per DC (4 replicas total for each range)
| Option | Replicas validating simultaneously | Use case |
|---|---|---|
-seq |
1 | Minimize impact during peak hours |
-dcpar |
1 per DC | Balance speed and safety in multi-DC clusters |
| (default) | All | Fastest repair during maintenance windows |
Usage:
nodetool repair -pr -dcpar my_keyspace
-j, --jobs (Parallel Table Repair)¶
Controls how many tables are repaired simultaneously on the node.
Usage:
# Repair 2 tables in parallel
nodetool repair -pr -j 2 my_keyspace
# Repair 4 tables in parallel
nodetool repair -pr -j 4 my_keyspace
Guidelines for -j value:
| Factor | Lower -j (1-2) | Higher -j (4+) |
|---|---|---|
| CPU cores | < 8 cores | 16+ cores |
| Memory | < 16 GB heap | 32+ GB heap |
| Disk I/O | HDD or saturated | Fast SSD with headroom |
| Network | Limited bandwidth | High bandwidth |
| Table count | Few large tables | Many small tables |
Memory impact:
Memory per repair session ≈ repair_session_space_in_mb × number of concurrent tables
With -j 4 and 256 MB per session = ~1 GB additional memory
Scope Limiting Options¶
-dc, --in-dc (Single Datacenter)¶
Restricts repair to nodes within a specific datacenter.
Usage:
# Repair only within dc1
nodetool repair -pr -dc dc1 my_keyspace
Use cases: - Minimize cross-datacenter network traffic - Repair after DC-specific outage - Staged rollout of repairs
-local, --in-local-dc¶
Repairs only with replicas in the same datacenter as the coordinator node.
# Repair within local DC only (run from node in target DC)
nodetool repair -pr -local my_keyspace
-hosts, --in-hosts¶
Limits repair to specific hosts, useful for targeted recovery.
Usage:
# Repair only between specific nodes
nodetool repair -pr -hosts 10.0.0.1,10.0.0.2,10.0.0.3 my_keyspace
Operational Options¶
--preview¶
Estimates repair work without executing, useful for planning.
nodetool repair -pr --preview my_keyspace
Output example:
Previewing repair for keyspace my_keyspace
Ranges to repair: 256
Estimated data to stream: 12.5 GiB
Mismatched ranges: 12 (4.7%)
Estimated duration: 45 minutes
--trace¶
Enables detailed tracing for repair sessions, useful for debugging.
nodetool repair -pr --trace my_keyspace
Trace output appears in system_traces keyspace and system logs.
-os, --optimise-streams (Cassandra 4.0+)¶
Optimizes streaming by calculating minimal data transfer paths.
Usage:
nodetool repair -pr -os my_keyspace
--force¶
Proceeds with repair even if some replicas are unavailable. Use with caution.
# Force repair with unavailable replicas
nodetool repair -pr --force my_keyspace
Warning: This can lead to inconsistent repair state. Only use when: - A replica is permanently gone and being replaced - Repair must proceed despite temporary unavailability - Understanding that full consistency is not guaranteed
--ignore-unreplicated-keyspaces¶
Skips keyspaces with replication factor of 1.
nodetool repair --ignore-unreplicated-keyspaces
Option Combinations¶
Recommended Combinations¶
| Scenario | Command | Description |
|---|---|---|
| Daily maintenance | nodetool repair -pr my_keyspace |
Incremental, primary range only |
| Weekly full check | nodetool repair -pr -full my_keyspace |
Full repair, primary range |
| Fast maintenance | nodetool repair -pr -j 2 my_keyspace |
Parallel (default) with 2 table threads |
| Conservative repair | nodetool repair -pr -seq my_keyspace |
Sequential, minimal impact |
| Multi-DC cluster | nodetool repair -pr -dcpar my_keyspace |
DC-parallel mode |
| Single DC repair | nodetool repair -pr -dc dc1 my_keyspace |
Limit to specific DC |
| After node recovery | nodetool repair -full my_keyspace |
Full repair, all ranges |
Options Compatibility Matrix¶
| Option | -pr | -full | -seq | -dcpar | -j | -dc | --paxos-only | --skip-paxos |
|---|---|---|---|---|---|---|---|---|
| -pr | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
| -full | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
| -seq | ✓ | ✓ | - | ✗ | ✓ | ✓ | ✗ | ✓ |
| -dcpar | ✓ | ✓ | ✗ | - | ✓ | ✓ | ✗ | ✓ |
| -j | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✗ | ✓ |
| -dc | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✗ | ✓ |
| --paxos-only | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | - | ✗ |
| --skip-paxos | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | - |
No --parallel Flag
Parallel repair is the default in Cassandra 4.0+. There is no explicit --parallel flag; to use sequential mode, specify -seq. To use datacenter-parallel mode, specify -dcpar.
Paxos Repair Options¶
--paxos-only¶
Repairs only the Paxos state used by lightweight transactions (LWTs), without repairing user table data.
# Repair Paxos state for all keyspaces
nodetool repair --paxos-only
# Repair Paxos state for a specific keyspace
nodetool repair --paxos-only my_keyspace
How it works:
This command runs a coordinated Paxos repair that synchronizes Paxos state stored in system.paxos across replicas. Unlike the automatic background Paxos repair (which only completes uncommitted transactions), --paxos-only also advances the Paxos repair low bound by writing to system.paxos_repair_history. This low bound is what enables garbage collection of old system.paxos data when using paxos_state_purging: repaired.
When to use:
- Clusters using
paxos_state_purging: repaired: Operators MUST run--paxos-onlyrepairs regularly (typically hourly) or ensure regular full repairs include the Paxos step. The automatic background repair does NOT advance the low bound, so without coordinated repairs,system.paxosgrows unboundedly. - Pre-4.1 clusters: Operators MUST schedule
--paxos-onlyrepairs manually since the automatic background repair is not available. - Before topology changes: Run on all nodes before bootstrap, decommission, replace, or move operations to reduce the risk of Paxos cleanup timeouts.
- After disabling automatic Paxos repairs: If
paxos_repair_enabledis set tofalse, coordinated Paxos repairs SHOULD be scheduled regularly for clusters using LWTs. - Troubleshooting LWT issues: When LWTs are timing out or behaving unexpectedly.
Relationship to automatic background Paxos repair (Cassandra 4.1+):
Cassandra 4.1+ includes an automatic background Paxos repair that runs every 5 minutes (controlled by paxos_repair_enabled). This background repair completes uncommitted transactions but does NOT replace the need for coordinated --paxos-only repairs. See Understanding the Two Paxos Repair Mechanisms for the full distinction.
Operational guidance:
- Running without a keyspace argument repairs Paxos state for all keyspaces. This is often RECOMMENDED because operators frequently do not know which keyspaces developers are using for LWTs.
- Paxos repairs are lightweight compared to full data repairs and complete quickly.
For more details on Paxos repair strategy and configuration, see Paxos Repairs in the Repair Strategies guide.
--skip-paxos¶
Skips the Paxos repair step during regular repairs, allowing data repair to proceed without checking Paxos state consistency.
# Skip Paxos repair, repair table data only
nodetool repair --skip-paxos my_keyspace
How it relates to --paxos-only:
| Option | Table Data | Paxos State |
|---|---|---|
| (no flag) | ✓ Repaired | ✓ Repaired |
--paxos-only |
✗ Skipped | ✓ Repaired |
--skip-paxos |
✓ Repaired | ✗ Skipped |
When to use:
- Emergency topology changes: When Paxos cleanup is failing (timing out,
CANCELLED) during bootstrap/decommission, you MAY skip Paxos repair temporarily to allow the topology change to proceed - Pre-4.1 clusters with manual Paxos repair: If running separate
--paxos-onlyrepairs on a schedule, you MAY skip Paxos during regular data repairs to avoid redundant work - Troubleshooting: To isolate whether issues are data-related or Paxos-related
Important caveat:
If you use --skip-paxos, Paxos state MUST be reconciled separately via --paxos-only repairs. Skipping Paxos repair without a replacement schedule WILL lead to LWT inconsistencies.
# Data repair only, skip Paxos (use when Paxos repairs are failing)
nodetool repair --skip-paxos my_keyspace
# Then run Paxos repairs separately once cluster is healthy
nodetool repair --paxos-only my_keyspace
Automated Alternative
Managing these options manually across large clusters is error-prone. AxonOps Adaptive Repair automates repair scheduling with intelligent defaults, eliminating the need to manually tune parallelism, scope, and timing options.
Next Steps¶
- Repair Concepts - Understanding how repair works
- Repair Strategies - Real-world implementation scenarios
- Scheduling Guide - Planning repair schedules