Redis Cluster: Hash Slots, Resharding, and the CROSSSLOT Trap
Cluster scales horizontally, but multi-key commands come with new rules. Hash tags are the escape hatch.
Redis Cluster shards the keyspace into 16,384 hash slots. Every key hashes (CRC16 mod 16384) to exactly one slot, and every slot lives on exactly one master. Scaling out is mechanical: move slots between masters.
What clients have to do
A key's owner can change. When it does, the old owner returns MOVED 7000 10.0.0.3:6379. A proper client caches the slot → node map and refreshes on MOVED. The smart client pattern (Lettuce, ioredis cluster) does this for you.
The CROSSSLOT error
Any multi-key command whose keys live in different slots fails:
MSET user:1 a user:2 b
# (error) CROSSSLOT Keys in request don't hash to the same slotSame rule applies to transactions (MULTI), Lua scripts, and SINTERSTORE. Keys touched in a single command must share a slot.
Hash tags
Put a brace-wrapped piece into the key; Redis hashes only that part. All keys with the same tag land on the same slot.
user:{42}:profile
user:{42}:sessions
MGET user:{42}:profile user:{42}:sessions # OK, same slotDesign your tags to reflect real co-locations (usually "tenant id" or "user id") — overdoing it recreates hot partitions.
Resharding live
CLUSTER RESHARD or redis-cli --cluster reshard moves slots online. During migration, keys in the moving slot may be in either node — clients handle this via ASK redirects, which are a one-shot version of MOVED. Don't panic if you see a spike of ASK in logs during a reshard — that's the protocol working.
When Cluster is the wrong answer
If you rely heavily on multi-key transactions, SUNION across arbitrary sets, or scripts over global state — sharding breaks those patterns. Sometimes the right move is a bigger single instance, not a cluster.