Module A-9·12 min read

The 16,384 hash slot model, CRC16 key hashing, hash tags for co-locating keys on the same slot, MOVED vs ASK redirections, multi-key command constraints in Cluster, and cluster-enabled client configuration.

Written by Jatin Jain Saraf · Architect of SupraScan

A-9 — Redis Cluster: Hash Slots and Data Distribution

Q: An application frequently uses the `MGET` command to fetch a user's profile and session data simultaneously: `MGET user:1001:profile user:1001:session`. After migrating from a standalone Redis instance to Redis Cluster, this command starts throwing `CROSSSLOT` errors. What is the most idiomatic way to fix this issue?

Rewrite the keys using hash tags, such as `{user:1001}:profile` and `{user:1001}:session`, ensuring both keys hash to the same slot. — Redis Cluster requires all keys in a multi-key command (like `MGET`, `MSET`, `SUNION`, or Lua scripts) to reside in the exact same hash slot. By default, `user:1001:profile` and `user:1001:session` will hash to completely different slots. By wrapping the common identifier in curly braces (`{user:1001}`), you create a "hash tag". Redis will only hash the string inside the braces, guaranteeing that both keys map to the exact same slot and the `MGET` command succeeds.

Q: When a Redis Cluster client sends a command to a node that does not own the hash slot for the requested key, what is the expected behavior?

The node returns a `MOVED` error containing the slot number and the IP/port of the correct node, prompting the client to update its local slot map and retry. — Unlike some distributed databases that act as proxies, Redis Cluster nodes do not route queries for you. This avoids the latency of an extra network hop. Instead, if you ask Node A for a key belonging to Node B, Node A replies with `-MOVED {slot} {Node B IP:Port}`. A proper Cluster-aware client library catches this error, updates its internal map of which node owns which slot, and automatically resends the command to Node B.

Q: What happens to a Redis Cluster if a primary node crashes and it has no replicas available to promote?

The entire cluster enters a `fail` state and refuses all read and write commands for all slots until the node is manually restored or the cluster is reconfigured. — By default, Redis Cluster prioritizes strict consistency of the keyspace over partial availability. If even a single hash slot out of the 16,384 becomes unassigned (because its primary crashed and there were no replicas to take over), the entire cluster transitions to a `cluster_state:fail` state. All commands across the entire cluster will return an error until full slot coverage is restored. (Note: this behavior can be changed by setting `cluster-require-full-coverage no` in the config, but C is the default and expected behavior).

Who this module is for: Your Redis dataset has grown beyond what a single node can hold in RAM, or your write throughput exceeds what a single node can handle. Redis Cluster is the answer — but it introduces constraints around multi-key operations, key routing, and command support that you must understand before adopting it. This module covers the Cluster model end-to-end.

Why Cluster?

A single Redis node has two hard limits:

RAM — the entire dataset must fit in one machine's memory. A 1TB dataset cannot fit on a 256GB node.
Write throughput — all writes go through one single-threaded event loop. At some point, you hit the wall (~1M ops/sec on modern hardware).

Redis Cluster solves both by distributing data across multiple primary nodes, each responsible for a subset of the keyspace.

The Hash Slot Model

Redis Cluster partitions the keyspace into 16,384 hash slots (numbered 0–16383). Every key belongs to exactly one slot:

slot = CRC16(key) % 16384

Hash slots are assigned to primary nodes. A 3-node cluster might assign:

Node 1 (primary-1): slots 0–5460
Node 2 (primary-2): slots 5461–10922
Node 3 (primary-3): slots 10923–16383

When a client issues GET user:1001, Redis computes CRC16("user:1001") % 16384 = 7638. Slot 7638 belongs to Node 2. The client sends the GET to Node 2.

MOVED and ASK Redirections

Cluster clients must track which node owns which slots. When a client sends a command to the wrong node, the node responds with a MOVED redirection:

GET user:1001 → sent to Node 1 (wrong node)
Node 1 → -MOVED 7638 10.0.1.52:6379
          ↑ slot ↑ correct node address

The client updates its local slot-to-node map and resends the command to the correct node. A well-implemented Cluster client handles this automatically and transparently — application code does not see MOVED errors.

ASK redirections are similar but temporary — used during slot migration (when a slot is being moved from one node to another). ASK means "ask this specific node for this specific command, but do not update your slot map."

GET product:999 → slot being migrated
Node 1 → -ASK 12345 10.0.1.53:6379
 
Client: sends ASKING command to 10.0.1.53, then resends GET product:999
Note: ASKING is not stored; next request for slot 12345 still goes to Node 1
      until migration completes and a MOVED is issued

Hash Tags: Controlling Key Placement

Multi-key commands (MGET, MSET, pipelines, Lua scripts, transactions) require all keys to be on the same node. In Cluster mode, this means all keys must be in the same hash slot.

Hash tags force a specific portion of the key to be used for slot computation:

CRC16(key) % 16384   → uses the full key
 
# With hash tag {tag}: only the portion inside {} is hashed
CRC16(tag) % 16384

user:1001:profile  → CRC16("user:1001:profile") % 16384 = slot A
user:1001:session  → CRC16("user:1001:session") % 16384 = slot B (different!)
 
{user:1001}:profile → CRC16("user:1001") % 16384 = slot X
{user:1001}:session → CRC16("user:1001") % 16384 = slot X (same slot!)

With hash tags, all keys for a specific user share the same slot — enabling multi-key operations:

// Without hash tags: MGET fails in Cluster (keys on different slots)
redis.mget('user:1001:profile', 'user:1001:session')  // CROSSSLOT error
 
// With hash tags: MGET works (all keys on the same slot)
redis.mget('{user:1001}:profile', '{user:1001}:session')  // ✓

Design rule: For related keys that must be accessed together, use hash tags from the start. Retrofitting hash tags requires migrating all existing keys.

Multi-Key Command Constraints

Commands that operate on multiple keys fail in Cluster if the keys span different slots:

MGET key1 key2 key3    → CROSSSLOT error if keys are on different nodes
MSET key1 v key2 v     → CROSSSLOT error
RPOPLPUSH list1 list2  → CROSSSLOT error
SUNIONSTORE dest src1 src2  → CROSSSLOT error if different slots
Lua scripts via EVAL   → CROSSSLOT error if KEYS span different nodes
MULTI/EXEC transactions → keys must be on same slot

Workarounds:

Hash tags — co-locate related keys on the same slot
Application-side batching — split multi-key operations by slot, execute per-node, merge results in the application
Single-key alternatives — replace MGET with a pipeline of GET commands (each routed to the correct node automatically by the Cluster client)

// Replace MGET with a pipeline in Cluster (each GET routed correctly)
const pipeline = redis.pipeline();
['user:1001', 'user:1002', 'user:1003'].forEach(key => pipeline.get(key));
const results = await pipeline.exec();

Cluster Setup

A minimal production Cluster requires 6 nodes: 3 primaries + 3 replicas (one replica per primary).

# Start 6 Redis instances with cluster mode enabled
# redis.conf for each:
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000    → ms to declare a node down (default 15000)
 
# Create the cluster (Redis 5.0+):
redis-cli --cluster create \
  10.0.1.1:6379 10.0.1.2:6379 10.0.1.3:6379 \
  10.0.1.4:6379 10.0.1.5:6379 10.0.1.6:6379 \
  --cluster-replicas 1
 
# Output will show slot distribution and ask for confirmation

Cluster-Aware Client: ioredis.Cluster

import { Cluster } from 'ioredis';
 
const redis = new Cluster([
  { host: '10.0.1.1', port: 6379 },
  { host: '10.0.1.2', port: 6379 },
  { host: '10.0.1.3', port: 6379 },
  // You only need to list some nodes — the client discovers the full topology
], {
  redisOptions: {
    password: process.env.REDIS_PASSWORD,
    commandTimeout: 500,
  },
  clusterRetryStrategy: (times) => Math.min(times * 100, 3000),
  scaleReads: 'slave',   // route reads to replicas
});
 
// Commands work transparently — MOVED redirects handled automatically
await redis.set('user:1001', 'data');
await redis.get('user:1001');
 
// Multi-key with hash tags
await redis.mget('{user:1001}:profile', '{user:1001}:session');

Cluster Node Commands

CLUSTER INFO              → cluster state, slot coverage, etc.
CLUSTER NODES             → full topology: node IDs, IPs, slots, roles
CLUSTER MYID              → this node's ID
CLUSTER KEYSLOT key       → compute the hash slot for a key
CLUSTER COUNTFAILUREREPORTS node-id
CLUSTER SLOTS             → slot-to-node mapping (deprecated; use CLUSTER SHARDS in 7.0+)
CLUSTER SHARDS            → (Redis 7.0+) slot ranges + node info

127.0.0.1:6379> CLUSTER INFO
cluster_enabled:1
cluster_state:ok                → 'fail' means cluster is in a degraded state
cluster_slots_assigned:16384    → all slots assigned
cluster_slots_ok:16384
cluster_slots_pfail:0           → slots where primary is probably down
cluster_slots_fail:0            → slots where primary is confirmed down
cluster_known_nodes:6
cluster_size:3                  → number of primaries
cluster_current_epoch:12

cluster_state:fail means at least one slot has no reachable primary — the cluster is refusing some or all write commands.

Automatic Failover in Cluster

Each primary in a Cluster has one or more replicas. When a primary fails, its replicas detect the failure via gossip (covered in A-11) and one replica promotes itself after a timeout:

cluster-node-timeout 5000   → if no PING response for 5s, node is considered down
# Failover completes in approximately 1-2× cluster-node-timeout

After failover, the new primary owns all slots previously owned by the failed node. If the failed primary had multiple replicas, only one promotes — the others continue replicating from the new primary.

If a primary fails with no available replica (the replica also failed), the cluster enters a cluster_state:fail state for those slots. No writes are accepted for the missing slots until the node recovers.

Limitations of Redis Cluster

No cross-slot operations: Multi-key commands must use hash tags. This is a design-time constraint — it requires forethought about which keys need to be co-located.

Limited database support: Cluster only uses database 0. The SELECT command is not available in Cluster.

Lua script constraints: EVAL scripts in Cluster must have all KEYS in the same slot. Multi-slot Lua scripts fail with CROSSSLOT. This limits some patterns that work fine on standalone Redis.

No blocking cross-node operations on multiple keys: a single-key BLPOP mylist is routed by any cluster-aware client to the exact node that owns mylist's slot, so a producer pushing to it and a consumer blocking on it always end up talking to the same node — that part works fine. The real constraint is multi-key blocking commands: BLPOP list1 list2 list3 fails outright with a CROSSSLOT error unless all three keys happen to hash to the same slot (which you'd normally force with hash tags, e.g. {orders}:list1). You can't blockingly wait across keys that live on different nodes.

Complexity: Cluster adds operational complexity — monitoring multiple nodes, handling resharding, managing replica assignments. For most workloads that fit within a single node's capacity, Sentinel (with a single large primary) is operationally simpler.

When to Use Cluster

Use Cluster when:

Dataset size exceeds available RAM on a single node
Write throughput exceeds ~500K ops/second on a single node
You need to shard a dataset too large for one node's memory across multiple nodes in the same region (Cluster is a single-region sharding mechanism, not a geo-distribution solution — see A-12 for what actual multi-region active-active requires)

Do not use Cluster when:

Your dataset fits on a single node — Sentinel is simpler
You rely heavily on multi-key commands without hash tag planning
Your application uses SELECT to separate databases (not supported in Cluster)
You use complex Lua scripts accessing multiple keys across slots

Summary

Redis Cluster distributes 16,384 hash slots across primary nodes; slot = CRC16(key) % 16384
MOVED redirections: permanent reroute to correct node; ASK redirections: temporary reroute during slot migration
Hash tags {tag} force slot computation on the tag — co-locate related keys: {user:1001}:profile and {user:1001}:session share a slot
Multi-key commands (MGET, MSET, Lua EVAL) require all keys on the same slot — use hash tags or application-side batching
Minimal production Cluster: 3 primaries + 3 replicas (one replica per primary)
Automatic failover when a primary fails — replica promotes after cluster-node-timeout; cluster enters fail state if no replica available
ioredis.Cluster handles MOVED/ASK transparently; scaleReads: 'slave' routes reads to replicas
Cluster limitations: no cross-slot ops without hash tags, only database 0, higher operational complexity than Sentinel

Next: A-10 — Resharding, Node Addition, and Live Slot Migration — adding nodes to a running cluster, migrating slots with zero downtime, and the ASKING redirection that enables live traffic during migration.

Knowledge Check

An application frequently uses the MGET command to fetch a user's profile and session data simultaneously: MGET user:1001:profile user:1001:session. After migrating from a standalone Redis instance to Redis Cluster, this command starts throwing CROSSSLOT errors. What is the most idiomatic way to fix this issue?

When a Redis Cluster client sends a command to a node that does not own the hash slot for the requested key, what is the expected behavior?

What happens to a Redis Cluster if a primary node crashes and it has no replicas available to promote?

Test your knowledge with more question sets

Sign in to keep reading

The rest of this module is free — sign in with Google to unlock it and track your progress.

PreviousModule A-8: Redis Sentinel: Quorum, Failover, and Split-Brain Prevention Next Module A-10: Resharding, Node Addition, and Live Slot Migration

Discussion

Join the discussion

Loading comments...