Redis Cluster: Hash Slots, Sharding, Redirects and Operations

Redis Cluster is the built-in way to shard Redis: it splits the keyspace into 16,384 hash slots, assigns those slots to several primary nodes, gives each primary its own replicas, and handles failover itself without Sentinel. There is no proxy. Clients connect to the nodes directly, keep a map of which node owns which slot, and follow MOVED and ASK redirects when that map is out of date.

This page covers how Cluster works and what goes wrong in production. For the Sentinel-or-Cluster decision and the step-by-step failover sequence, our Redis high availability guide covers both in depth.

Every key belongs to exactly one slot, calculated as CRC16(key) mod 16384. Each primary owns a subset of the slots, and in a stable cluster each slot is served by exactly one primary. 16,384 is also the theoretical ceiling on primaries, but the Redis Cluster specification suggests staying around 1,000 nodes and sets linear scalability up to that size as a design goal.

Any node will tell you where a key lands:

CLUSTER KEYSLOT user:1000
CLUSTER KEYSLOT {user:1000}:cart

Hash tags change the calculation. If a key contains a { followed later by a }, with at least one character between them, only the text between the first { and the next } is hashed. So {user1000}.following and {user1000}.followers share a slot. The edge cases catch people out: foo{}{bar} is hashed whole because the first braces are empty, and foo{bar}{zap} hashes only bar.

Hash tags keep related keys together, and they are also how teams build hot spots. Tagging every key of a large tenant with {tenant42} puts that whole tenant in one slot on one primary. Tag by the smallest unit that needs atomic multi-key access, usually a user, an order or a session.

Moving from a single instance to Cluster is close to transparent for single-key commands. It is not transparent for anything that touches several keys:

• Multi-key commands such as MSET, SINTER or RENAME run only when every key is in the same slot; otherwise the node returns a CROSSSLOT error. Keys used together in MULTI/EXEC transactions and Lua scripts follow the same rule.
• One database. Redis Cluster supports only database 0 and rejects SELECT, so applications that separate data by database number need key prefixes. Valkey 9.0 added numbered databases in cluster mode, one place the two forks now differ.
• Whole-database commands are per node. Anything that scans, counts or flushes the keyspace sees only the connected node's share, so tooling has to visit every primary.
• Pub/Sub. Classic Pub/Sub messages are propagated over the cluster bus to every node. Redis 7.0 added sharded Pub/Sub (SPUBLISH and SSUBSCRIBE), which maps channels to slots like keys and keeps traffic inside one shard.
• Big keys stay big. A key lives in one slot, so a multi-gigabyte sorted set sits on one primary and its replicas. Cluster spreads keys, not values.

A node that receives a command for a slot it does not own does not forward it. It answers with a redirect, and the client has to retry elsewhere:

GET x
-MOVED 3999 127.0.0.1:6381

MOVED means the slot belongs to another node. A cluster-aware client updates its slot map and sends future requests for that slot straight to the new owner. ASK appears only while a slot is being migrated, when a key may already have moved. The client sends ASKING and then the command to the target node for that single request, and keeps using the old node for everything else until the migration finishes.

The client library matters: it must handle both redirects, refresh its slot map and route each command by slot. redis-cli -c follows redirects; plain redis-cli just prints them. Resharding also has a cost. During key-by-key migration, requests for the moving slot take extra round trips, and multi-key operations on it can fail until it completes. Valkey 9.0 introduced atomic slot migration, which moves a whole slot before switching ownership and avoids those mid-migration redirects.

Every node opens a second TCP port for node-to-node traffic, the cluster bus. By default it is the client port plus 10000, so 16379 for a node on 6379, unless cluster-port sets it. Every node connects to every other node and uses a gossip protocol over the bus to share state, detect failures and coordinate failovers. Both ports must be open between all nodes; opening 6379 but not 16379 leaves nodes that never form a cluster.

When a primary stays unreachable for longer than cluster-node-timeout, one of its replicas is promoted after a vote among the primaries. Our failover walkthrough covers that sequence. Four settings shape what clients see while it happens:

• cluster-node-timeout: how long before a node counts as failing. Set it too low and a VM pause or a slow fork triggers failovers nobody needed.
• cluster-require-full-coverage: yes by default, which stops writes across the cluster if any slot has no serving node. Set it to no only if serving part of the keyspace beats serving none.
• cluster-allow-reads-when-down: no by default, so nodes stop serving all traffic once the cluster is marked as failed.
• cluster-migration-barrier: controls replica migration, in which a spare replica moves to a primary that has lost its own. One extra replica can then protect several shards.

Replication is asynchronous, and the specification states plainly that Redis Cluster can lose writes it has acknowledged, with a wider window for clients on the minority side of a network partition. Treat it as a fast, highly available store, not a strongly consistent one.

Sentinel adds automatic failover to one dataset on one primary; Cluster adds sharding for when the data or write rate no longer fits on one node. If one node with headroom holds everything, Sentinel keeps full multi-key semantics and simpler clients. The comparison table and decision rules are in Redis high availability: Sentinel vs Cluster.

Redis's documentation sets a minimum of three primaries and recommends a six-node cluster, three primaries and three replicas, for deployment. From there:

• Derive the shard count from memory and write rate. Divide the dataset plus growth by what one primary can hold while leaving room for the persistence fork and replication buffers; our Redis memory guide explains why resident memory can run well above the dataset during a snapshot. Then check the write rate each primary will carry.
• Keep shards even. redis-cli --cluster rebalance balances slot counts, and the Redis tutorial notes it does not look at how keys are distributed. Hot tags and big keys need fixing in the key design, not by moving slots.
• Separate failure domains. Never place a primary and its own replica on the same host, hypervisor or availability zone.
• Grow early. Adding a shard means redis-cli --cluster add-node and then resharding slots onto the new node. Do it with headroom, not during an incident.

A new cluster with one replica per primary is created with --cluster-replicas 1:

redis-cli --cluster create 10.0.0.1:6379 10.0.0.2:6379 10.0.0.3:6379 \
  10.0.0.4:6379 10.0.0.5:6379 10.0.0.6:6379 --cluster-replicas 1

• Containers with port mapping. Redis Cluster does not support NAT or remapped ports, because nodes announce addresses the others cannot reach. Redis's documentation points Docker users to host networking.
• Clients with a stale slot map. After a failover or reshard, a client that refreshes its map too rarely keeps hitting the wrong node and turns every request into two.
• CROSSSLOT errors after migration. Code that worked on a single instance fails the first time a transaction touches two unrelated keys. Catch these with integration tests against a real cluster before cutover.
• Full-coverage outages. Losing a primary and its only replica stops writes to the whole cluster under the default settings. Replica counts, failure domains and replica migration prevent it.

For symptoms such as CLUSTERDOWN errors after a reshard, see Redis troubleshooting.

Cluster rewards getting the key design and topology right at the start, and punishes fixing them under load. If you are moving from a single instance or Sentinel to Cluster, resharding a cluster that has grown unevenly, or running one that fails over more often than it should, AceMQ's Redis support engineers work with open-source Redis Cluster every day, and Valkey support covers the same topology on the Linux Foundation fork. If you would rather not run it yourself, Redis managed services covers operations end to end.

• Redis: Redis Cluster specification
• Redis: Scale with Redis Cluster (tutorial and configuration parameters)
• Redis: Multi-key operations
• Redis: CLUSTER KEYSLOT
• Redis: Pub/Sub (sharded Pub/Sub)
• Valkey: Introducing Valkey 9.0
• Valkey: Atomic slot migration
• Valkey: Numbered databases in cluster mode