Understanding Hash Slots: How Redis Cluster Distributes Data

1. What hash slots are and why Redis Cluster needs them

Redis Cluster does not distribute data by server name or by a hash ring with virtual nodes. Instead it relies on a fixed concept called hash slots. Every key in the entire cluster is deterministically assigned to exactly one of 16384 hash slots, and every node in the cluster owns a specific subset of those slots. This model is the reason a client can talk to any node at all and still reliably learn where a given key actually lives.

Without hash slots, every client would have to maintain a full mapping table from millions of keys to nodes, or query a central coordinator on every request, which would quickly become a bottleneck. The fixed grid of 16384 slots reduces this problem to a compact, cacheable table: instead of tracking individual keys, a client only needs to know which node owns which slot range. That is what makes horizontal scaling practical without routing every read through an extra proxy layer.

2. The 16384-slot model in detail

The number 16384, that is 2 to the power of 14, is not arbitrary. It balances two conflicting requirements: the slot bitmap that every node broadcasts to other cluster members over the gossip protocol must stay small enough not to overwhelm heartbeat traffic, yet large enough to still allow fine-grained distribution across thousands of nodes. At 16384 bits that works out to exactly 2048 bytes per bitmap, a value the Redis developers chose deliberately to keep clusters with up to roughly 1000 nodes practical.

Each of the 16384 hash slots is permanently assigned to one Redis node, and the sum of all assigned slots in a healthy cluster must always equal exactly 16384. If even a single slot is missing from the assignment, the cluster reports itself as degraded by default and refuses write operations, provided the setting cluster-require-full-coverage is enabled. This completeness check prevents data for an unassigned slot range from silently getting lost.

3. CLUSTER KEYSLOT: tracing the slot calculation

Redis computes the hash slot of a key using the formula CRC16(key) mod 16384. The CRC16 algorithm is deterministic and fast, so every client and every node independently arrives at the same result without needing to coordinate. The command CLUSTER KEYSLOT lets you query this value directly through redis-cli, which is indispensable when debugging distribution issues or designing a key schema.

In practice you almost never need to compute the CRC16 formula by hand. Instead you simply ask the running cluster: CLUSTER KEYSLOT user:1000 returns the responsible slot immediately. That is especially helpful for understanding why two related keys like order:1 and order:2 can end up on completely different nodes, even though they are logically connected.

# Trace the slot calculation for individual keys
redis-cli -c -h node1.cluster.internal -p 6379 CLUSTER KEYSLOT user:1000
# (integer) 5474

redis-cli -c CLUSTER KEYSLOT order:1
# (integer) 15871

redis-cli -c CLUSTER KEYSLOT order:2
# (integer) 3300

# Both keys land on different slots -> possibly different nodes
# With a hash tag we force the same slot (see section 6)
redis-cli -c CLUSTER KEYSLOT "order:{42}:items"
# (integer) 9689
redis-cli -c CLUSTER KEYSLOT "order:{42}:status"
# (integer) 9689

4. Slot assignment to nodes: CLUSTER NODES and CLUSTER SLOTS

If you need to know which node is responsible for which slot range, use CLUSTER NODES or CLUSTER SLOTS. CLUSTER NODES returns one line per node with its ID, address, role as master or replica, connection status, and the assigned hash slots as from-to ranges. CLUSTER SLOTS returns the same information in a structured form for clients that want to build routing tables programmatically, such as modern Redis client libraries with built-in cluster support.

This slot assignment is not static for the lifetime of the cluster. It can be changed at any time through CLUSTER SETSLOT, for example when adding a new node or performing targeted rebalancing. Importantly, any client that has cached a stale mapping receives a MOVED reply pointing to the new node on its first misdirected request. Modern clients then automatically refresh their internal slot table without any intervention from the application.

redis-cli -c CLUSTER NODES
# 07c37dfeb235213a872192d90877d0cd55635b91 127.0.0.1:6379@16379 myself,master - 0 0 1 connected 0-5460
# 67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 127.0.0.1:6380@16380 master - 0 1690000001000 2 connected 5461-10922
# 292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 127.0.0.1:6381@16381 master - 0 1690000002000 3 connected 10923-16383
# 6ec23923021cf3ffec47632106199cb7f496ce01 127.0.0.1:6382@16382 slave 07c37dfeb235213a872192d90877d0cd55635b91 0 1690000003000 1 connected

redis-cli -c CLUSTER SLOTS
# 1) 1) (integer) 0
#    2) (integer) 5460
#    3) 1) "127.0.0.1"
#       2) (integer) 6379
#       3) "07c37dfeb235213a872192d90877d0cd55635b91"

5. Why multi-key operations fail across slot boundaries

Redis Cluster only allows multi-key commands like MGET, MSET, MULTI/EXEC transactions, or Lua scripts run with EVAL when all involved keys map to the same hash slot. If a request violates this rule, the node responds with the error CROSSSLOT Keys in request don't hash to the same slot. This is not an arbitrary restriction but a direct consequence of the architecture: a node can only guarantee an atomic operation for data it actually owns.

In practice this error usually catches teams off guard when code that was previously tested against a single-node instance suddenly fails under cluster operation. An MGET over user:1000:profile and user:1000:settings only works if both keys land on the same hash slot, which without explicit control is pure chance, since CRC16 is computed over the full key string and different suffixes can lead to different slots.

For applications that depend on server-side transactions or Lua scripts spanning several logically related keys, understanding this boundary is essential for the data model. Anyone who needs multi-key operations across slot boundaries must either restructure the application logic toward single-key operations per round trip, or deliberately ensure that related keys land on the same slot.

# Without a hash tag: CROSSSLOT error on multi-key access
redis-cli -c MSET user:1000:profile "{}" user:1000:settings "{}"
# (error) CROSSSLOT Keys in request don't hash to the same slot

redis-cli -c MGET user:1000:profile user:1000:settings
# (error) CROSSSLOT Keys in request don't hash to the same slot

# With a hash tag: guaranteed same slot, operation succeeds
redis-cli -c MSET "user:{1000}:profile" "{}" "user:{1000}:settings" "{}"
# OK
redis-cli -c MGET "user:{1000}:profile" "user:{1000}:settings"
# 1) "{}"
# 2) "{}"

6. Hash tags: co-locating keys on purpose

The solution to the CROSSSLOT problem is hash tags. If a key contains curly braces, Redis computes the hash slot only from the part between the first opening and the first closing brace, not from the entire key string. The key user:{1000}:profile and the key user:{1000}:settings are therefore guaranteed to land on the same slot, because both use the same hash tag content 1000, even though the rest of the strings differ.

This pattern is the standard way to keep related data together in Redis Cluster, for example all data structures belonging to a single tenant, an order, or a session. Important caveat: if the hash tag is chosen too coarsely, for example a single shared tag for every key across an entire shop instead of per customer, an enormous number of keys accumulate on a single hash slot, resulting in a hot slot and uneven load distribution.

A good rule of thumb: choose hash tags granular enough to represent exactly the unit for which atomic multi-key operations are needed, but no coarser. For an application with millions of users that usually means one hash tag per user ID or per tenant ID, never a globally shared tag that forces all keys onto a single slot and effectively defeats cluster-wide distribution.

7. Resharding: migrating slots between nodes

When a cluster grows by adding new nodes, or when load needs to be redistributed, hash slots must be migrated from existing nodes to new ones, a process Redis calls resharding. The manual path uses CLUSTER SETSLOT with the states MIGRATING and IMPORTING: the source node marks a slot as migrating, the target node marks it as importing, and then the individual keys in that slot are transferred one by one with MIGRATE.

The command CLUSTER GETKEYSINSLOT returns the list of keys within a given slot so a migration script can process them one at a time. During the migration the cluster remains available for reads: a client that requests an already migrated key from the old node receives an ASK redirect to the new node instead of an error. That allows resharding to happen live, without downtime, as long as the application correctly handles ASK and MOVED replies.

In practice almost nobody drives the manual sequence of CLUSTER SETSLOT and MIGRATE directly. The command-line tool redis-cli --cluster reshard automates the entire process, including even distribution across multiple target nodes, and is the recommended path for production resharding operations.

# Manual migration of a single slot (principle)
redis-cli -h target -p 6380 CLUSTER SETSLOT 5461 IMPORTING <source-node-id>
redis-cli -h source -p 6379 CLUSTER SETSLOT 5461 MIGRATING <target-node-id>

redis-cli -h source -p 6379 CLUSTER GETKEYSINSLOT 5461 100
# 1) "order:{5461-sample}:1"
# 2) "order:{5461-sample}:2"

redis-cli -h source -p 6379 MIGRATE target 6380 "" 0 5000 KEYS \
  "order:{5461-sample}:1" "order:{5461-sample}:2"
# OK

# After migration completes: assign final slot ownership
redis-cli -h source -p 6379 CLUSTER SETSLOT 5461 NODE <target-node-id>
redis-cli -h target -p 6380 CLUSTER SETSLOT 5461 NODE <target-node-id>

# Recommended: automated resharding via redis-cli
redis-cli --cluster reshard node1.cluster.internal:6379 \
  --cluster-from <source-node-id> --cluster-to <target-node-id> \
  --cluster-slots 1000 --cluster-yes

8. Monitoring slot distribution and hot slots

An even distribution of the 16384 hash slots across all master nodes is a prerequisite for even load, but it does not by itself guarantee even access load. A single extremely popular key, for example a global counter or a frequently read configuration object, can put significantly more pressure on one slot, and therefore one node, than all the others. This phenomenon is called a hot slot, and plain slot counting will not reveal it.

For monitoring, a combination of CLUSTER COUNTKEYSINSLOT per slot to check the raw key count, and redis-cli --hotkeys or redis-cli --bigkeys to identify individual heavily accessed or large keys, works well. Regular sampling across all 16384 hash slots shows whether the slot assignment still matches actual access patterns, or whether targeted resharding is needed to relieve an overloaded node.

# Sample key counts across all 16384 slots to spot uneven distribution
for slot in 0 5460 5461 10922 10923 16383; do
  count=$(redis-cli -c CLUSTER COUNTKEYSINSLOT "$slot")
  echo "slot $slot: $count keys"
done
# slot 0: 812 keys
# slot 5460: 799 keys
# slot 5461: 214032 keys   <- suspiciously high, likely a hot slot
# slot 10922: 803 keys
# slot 10923: 790 keys
# slot 16383: 811 keys

# Identify frequently accessed keys within a suspected hot slot
redis-cli -c --hotkeys
redis-cli -c --bigkeys

9. Common pitfalls when working with hash slots

The most common mistake is assuming that Redis Cluster distributes data evenly on its own, without the application needing to do anything about it. Without deliberate key design using hash tags, logically related data lands on random slots, which makes multi-key operations impossible and forces application code into many individual round trips instead of a single efficient operation.

A second pitfall is overusing hash tags: choosing a tag that is too coarse causes millions of keys to pile up on a single hash slot, turning that one node into a bottleneck while the remaining 16383 slots sit nearly idle. A third pitfall involves cluster-require-full-coverage: disabling this setting in production means the cluster accepts write operations even when individual slots are temporarily unassigned, which can lead to silent, unnoticed data loss.

10. Summary

Hash slots are the foundation of data distribution in Redis Cluster: 16384 fixed slots, every key assigned to exactly one slot via CRC16(key) mod 16384, and every node responsible for a contiguous range. CLUSTER KEYSLOT makes this mapping traceable at any time, while CLUSTER NODES and CLUSTER SLOTS show the current assignment. Multi-key operations fail with the CROSSSLOT error as soon as involved keys belong to different slots, and hash tags in curly braces solve this by deliberately forcing the same slot.

Resharding with CLUSTER SETSLOT, MIGRATE, and the convenient redis-cli --cluster reshard moves slots without downtime whenever the cluster grows or load needs redistribution. Choosing hash tags too coarsely risks hot slots that overload a single node, while CLUSTER COUNTKEYSINSLOT and redis-cli --hotkeys surface such imbalances early. A well thought out key schema with granular hash tags is therefore not an afterthought optimization, but a basic requirement for stable cluster operation.

11. FAQ: hash slots in Redis Cluster