Redis "CLUSTERDOWN The cluster is down": What It Means and How to Recover

CLUSTERDOWN The cluster is down is what a Redis Cluster node replies when it has decided the cluster is not healthy enough to serve queries. It is not a bug and it is not one node misbehaving: it is the cluster protecting your data. To fix it you need to know which of two conditions triggered it, and that takes one command.

Redis splits the key space into 16384 hash slots, and every slot must belong to a reachable primary. The Redis Cluster documentation is clear that the cluster continues through small failures but becomes unavailable during larger ones, for example when the majority of primaries are unreachable. Valkey, which forked from Redis, uses the same three error messages and the same rules.

Three CLUSTERDOWN errors, three meanings

• CLUSTERDOWN The cluster is down: the node considers the cluster state fail and rejects the command.
• CLUSTERDOWN The cluster is down and only accepts read commands: the same state, but cluster-allow-reads-when-down is set to yes, so reads still work and this write was refused.
• CLUSTERDOWN Hash slot not served: the key hashes to a slot that no node owns. You often see this on a freshly created cluster where slots were never assigned, or after a node was removed without moving its slots first.

Why the cluster goes down

In the Redis source, a node flips its cluster state to fail for one of two reasons:

1. Slot coverage is broken. With cluster-require-full-coverage yes (the default), if any of the 16384 slots has no owner or is owned by a node flagged FAIL, the whole cluster stops accepting queries, not just the keys in those slots. The typical story: a primary dies and has no working replica to take over, so its slots stay uncovered.
2. The node is in a minority. If a node cannot reach a majority of the primaries that serve slots, it marks the cluster as failed. The documentation describes this as a node that cannot sense the majority of other primaries for longer than the node timeout entering an error state. A network partition, a security group change or an overloaded host can do this.

Diagnose with CLUSTER INFO

$ redis-cli -c -h 10.0.3.11 -p 6379 SET user:42 x
(error) CLUSTERDOWN The cluster is down

$ redis-cli -h 10.0.3.11 -p 6379 CLUSTER INFO | head -7
cluster_state:fail
cluster_slots_assigned:16384
cluster_slots_ok:10923
cluster_slots_pfail:0
cluster_slots_fail:5461
cluster_known_nodes:6
cluster_size:3

The CLUSTER INFO fields tell you which case you are in. cluster_slots_fail above zero means slots belong to a node in FAIL state: a coverage problem. cluster_slots_assigned below 16384 means some slots have no owner at all. If every slot looks fine but cluster_state is still fail, ask the same question from a node on the other side of the network: you are probably talking to a node in a minority partition. cluster_slots_pfail counts slots whose owner is only suspected to be down; those still work until the suspicion is confirmed.

# which node owns the failed slots, and does it have a replica?
$ redis-cli -h 10.0.3.11 -p 6379 CLUSTER NODES | grep -E "master|fail"

# full consistency check from any node
$ redis-cli --cluster check 10.0.3.11:6379

Getting back up

1. Bring the failed primary back if you can. Often it is a restarted process or a full disk. Once it rejoins and its slots are covered, the cluster returns to ok on its own. A restarted primary waits a short moment before accepting writes so it can receive a configuration update first, so do not panic over the first second or two.
2. Promote a replica manually if automatic failover did not happen. Run CLUSTER FAILOVER FORCE on the replica you want to promote when its primary is unreachable. FORCE still needs a majority of primaries to authorize the new configuration. A replica that was disconnected too long may refuse to fail over automatically because of cluster-replica-validity-factor, which is exactly when a manual failover helps.
3. Assign or move missing slots. For "Hash slot not served", redis-cli --cluster check lists uncovered slots and redis-cli --cluster fix can assign them. Check first: if those slots had data on a node that is gone, fixing coverage gives you empty slots, not your data back.

Settings that change the behaviour

• cluster-require-full-coverage no keeps the healthy shards serving their keys while some slots are down. Good for caches where partial availability beats none; risky when the application assumes all keys are reachable.
• cluster-allow-reads-when-down yes serves reads while the cluster is down, as long as the node believes it owns the slot. The redis.conf comments recommend it for caches and for clusters with fewer than three shards, accepting that reads may be stale.
• cluster-node-timeout (15000 ms in the default redis.conf) decides how quickly a primary is declared failed and replaced. Lower means faster failover and more false alarms on a busy network.
• cluster-migration-barrier (default 1) lets spare replicas move to a primary that has none, so one extra replica can protect several shards.

If clients keep writing to an old node after a failover in a non-cluster setup, that is a different error; see our Redis READONLY guide.

What changes with large datasets

• Every shard needs a replica, at least one. With big nodes, bringing a dead primary back can take far longer than promoting a replica. A shard without a replica turns a single host failure into a full cluster outage under the default full coverage rule.
• Restarts are slow. A large node has to load its dataset before it can serve, and it answers LOADING while it does, see Redis LOADING dataset in memory. If both a primary and its replica restart together, for example during a careless rolling upgrade, the slots stay uncovered until one of them finishes loading.
• After failover, expect resync traffic. The old primary rejoins as a replica and may need a full sync of tens of gigabytes. Size replication backlog and output buffers so this does not loop, and do not start the next maintenance step until replication is stable.
• Resharding moves real data. Moving slots copies keys between nodes, and very large keys make slot migration slow. Plan resharding in quiet hours and watch latency on both nodes.
• Spread nodes across failure domains. Put a primary and its replica in different racks or availability zones, and avoid placing a majority of primaries in one zone, or a single zone outage can leave the survivors in a minority.
• Rehearse. Kill a primary in staging at full size and time how long the cluster stays in fail. That number, not the node timeout, is your real recovery time.