CLUSTERDOWN error

The cluster can't serve the command because a hash slot has no working node.

A Redis cluster returns this error when it can't serve your command. The message has two versions:

CLUSTERDOWN Hash slot not served
CLUSTERDOWN The cluster is down
  • Hash slot not served means that no node serves the key's hash slot. This happens when some slots were never assigned to a node, for example, in a cluster you haven't finished setting up.
  • The cluster is down means that the cluster is in a failed state. By default, a cluster stops serving commands when any hash slot has no working node. For example, this happens when a primary node fails and has no replica to take its place.

In client libraries

Client libraryException or error typeMessage
redis-py ClusterDownError The cluster is down
Jedis JedisClusterException CLUSTERDOWN The cluster is down
node-redis SimpleError
Test with err.message.startsWith('CLUSTERDOWN')
CLUSTERDOWN The cluster is down
Lettuce
The async API wraps the exception in an ExecutionException (get()) or a CompletionException (join()).
RedisCommandExecutionException CLUSTERDOWN The cluster is down
go-redis redis.Error
Test with redis.IsClusterDownError(err)
CLUSTERDOWN The cluster is down
ioredis ReplyError
Test with err.message.startsWith('CLUSTERDOWN')
CLUSTERDOWN The cluster is down
StackExchange.Redis
NRedisStack uses StackExchange.Redis, so it raises the same exceptions. The sync and async APIs raise the same exceptions.
RedisServerException CLUSTERDOWN The cluster is down
Predis Predis\Response\ServerException
Test with $e->getErrorType() === 'CLUSTERDOWN'
CLUSTERDOWN The cluster is down
redis-rb Redis::CommandError CLUSTERDOWN The cluster is down (redis://<host>:<port>)
redis-rs
The sync and async APIs raise the same errors.
ErrorKind::Server(ServerErrorKind::ClusterDown) ClusterDown: The cluster is down

Example

After a primary with no replica fails, the other nodes stop serving commands, even for their own keys:

> GET foo
(error) CLUSTERDOWN The cluster is down

How to fix it

  1. Check the state of the cluster with CLUSTER INFO. cluster_state:fail means the cluster is down. cluster_slots_assigned shows how many of the 16384 slots have a node.
  2. Find the failed nodes with CLUSTER NODES. A failed node has fail in its flags.
  3. Bring the failed node back, or move its slots to working nodes. If slots were never assigned, assign them. redis-cli --cluster create assigns all the slots when it creates a cluster.

To keep the cluster working when a primary fails, give each primary at least one replica. A replica then takes its primary's place.

Two settings change what a cluster does when some slots have no working node:

  • cluster-require-full-coverage no lets nodes keep serving the slots that still have a working node.
  • cluster-allow-reads-when-down yes lets nodes serve reads while the cluster is in a failed state. Writes then get CLUSTERDOWN The cluster is down and only accepts read commands.

See Redis Cluster configuration parameters.

RATE THIS PAGE
Back to top ↑