redis.exceptions.ClusterDownError: CLUSTERDOWN The cluster is down
ID: database/redis-cluster-down
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 7 | active | — | — | — |
Root Cause
A Redis Cluster node reports that the cluster is in a failed state. This occurs when one or more hash slots are not covered (no master serving them), typically because a master node is down and has no available replica for failover. The cluster requires all 16384 hash slots to be assigned and served to accept commands.
genericWorkarounds
-
88% success Identify and recover the failed node or assign its slots to another node
Check cluster state: redis-cli cluster info (look for cluster_state:fail). Find unassigned slots: redis-cli cluster slots. If a master is down but recoverable, restart it and wait for it to rejoin. If permanently lost, use: redis-cli --cluster fix <any-alive-node>:6379 to reassign orphaned slots to existing masters.
-
85% success Promote a replica to master for the failed node's slots
If the failed master has a replica: redis-cli -h replica-host -p 6379 CLUSTER FAILOVER TAKEOVER. The replica will assume the master role and serve its slots. If no replica exists, add a new node: redis-cli --cluster add-node new-node:6379 existing-node:6379, then reshard slots to it.
Dead Ends
Common approaches that don't work:
-
Restarting all cluster nodes simultaneously to fix the cluster state
80% fail
Restarting all nodes at once causes a full cluster outage and can lead to data loss if nodes have unsaved data. Cluster state recovery depends on node gossip, and a full restart can cause split-brain if nodes come up at different times with stale cluster state.
-
Setting cluster-require-full-coverage to no as a permanent solution
65% fail
With cluster-require-full-coverage no, the cluster accepts commands for available slots but returns errors for keys in unavailable slots. This causes partial failures that are difficult for applications to handle correctly. It masks the real problem (missing slots) instead of fixing it.