🚨 Redis Error Guide: 'CROSSSLOT Keys in request don't hash to the same slot' — Use Hash Tags

Overview

CROSSSLOT Keys in request don't hash to the same slot is a Redis Cluster error. In cluster mode the keyspace is split into 16384 hash slots spread across masters, and any single multi-key command (MGET, MSET, SINTERSTORE, DEL a b c, a MULTI/EXEC touching several keys, a Lua script with multiple KEYS) requires that every key it touches lives in the same slot. When the keys hash to different slots, Redis rejects the command.

The literal error clients receive:

(error) CROSSSLOT Keys in request don't hash to the same slot

This is not a bug or a topology fault — it is a fundamental constraint of Redis Cluster. The fix is data modeling: use hash tags ({...}) so related keys deliberately land in the same slot, or restructure the operation so it does not span slots. Understanding slot hashing is the whole game here.

Symptoms

• Multi-key commands fail with CROSSSLOT only in cluster mode (they work fine on a standalone Redis).
• MSET, MGET, SUNIONSTORE, multi-key DEL, or MULTI/EXEC across keys are rejected.
• Lua scripts fail when their KEYS span slots.

redis-cli -c MSET user:1 a user:2 b

(error) CROSSSLOT Keys in request don't hash to the same slot

redis-cli -c CLUSTER KEYSLOT user:1
redis-cli -c CLUSTER KEYSLOT user:2

(integer) 8404
(integer) 5474

Different slot numbers confirm why the multi-key command was rejected.

Common Root Causes

1. Multi-key command across unrelated keys

MGET/MSET/DEL with keys that naturally hash to different slots.

redis-cli -c CLUSTER KEYSLOT session:abc
redis-cli -c CLUSTER KEYSLOT session:def

(integer) 12045
(integer) 3388

2. Missing hash tags on keys that must be operated together

Keys that should co-locate (e.g. all keys for one user) were named without a {tag}, so they scatter.

# Without a tag, these are in different slots
redis-cli -c CLUSTER KEYSLOT cart:items:42
redis-cli -c CLUSTER KEYSLOT cart:total:42

3. Transactions / Lua touching multiple slots

A MULTI/EXEC block or an EVAL whose KEYS[] span slots hits CROSSSLOT.

redis-cli -c EVAL "return redis.call('MGET', KEYS[1], KEYS[2])" 2 a b

(error) CROSSSLOT Keys in request don't hash to the same slot

4. Set/zset store operations across slots

SINTERSTORE, ZUNIONSTORE, SMOVE, RENAME require source and destination in the same slot.

redis-cli -c CLUSTER KEYSLOT src
redis-cli -c CLUSTER KEYSLOT dst

Diagnostic Workflow

Step 1: Confirm you are in cluster mode

redis-cli INFO cluster | grep cluster_enabled
redis-cli CLUSTER INFO | grep cluster_state

cluster_enabled:1
cluster_state:ok

CROSSSLOT only occurs when cluster_enabled:1.

Step 2: Compute the slot of each key involved

redis-cli -c CLUSTER KEYSLOT <key1>
redis-cli -c CLUSTER KEYSLOT <key2>

Different numbers = the cause of the error.

Step 3: See how the hash tag changes the slot

redis-cli -c CLUSTER KEYSLOT '{user:42}:cart'
redis-cli -c CLUSTER KEYSLOT '{user:42}:total'

(integer) 9711
(integer) 9711

Only the substring inside {} is hashed, so both keys share a slot.

Step 4: Inspect slot ownership across the cluster

redis-cli CLUSTER NODES | awk '{print $2, $9}'
redis-cli CLUSTER SLOTS

Step 5: Find the offending command in the app/log

redis-cli SLOWLOG GET 10
sudo journalctl -u myapp --no-pager | grep -iE 'CROSSSLOT|MSET|MGET' | tail

Example Root Cause Analysis

At 10:40, after migrating a shopping-cart service from a single Redis to a 3-master cluster, checkout starts failing with CROSSSLOT Keys in request don't hash to the same slot. The service reads a cart’s items and total together with MGET cart:items:42 cart:total:42.

Computing the slots shows the two keys landed on different masters:

redis-cli -c CLUSTER KEYSLOT cart:items:42   # -> 4821
redis-cli -c CLUSTER KEYSLOT cart:total:42   # -> 15098

The root cause is the key naming: nothing forces the two related keys into the same slot. The fix is to introduce a hash tag around the shared identifier so every key for a given cart co-locates:

# New key names put the user id in a hash tag
redis-cli -c CLUSTER KEYSLOT '{cart:42}:items'   # -> 6390
redis-cli -c CLUSTER KEYSLOT '{cart:42}:total'   # -> 6390

With keys renamed to {cart:42}:items and {cart:42}:total, the MGET (and a later MULTI/EXEC that updates both) targets a single slot and succeeds. The migration script rewrote existing keys into the tagged scheme. Where operations genuinely span unrelated data (e.g. cross-user aggregation), the code was changed to issue per-key requests and combine results client-side instead of a single multi-key command.

Prevention Best Practices

• Design keys with hash tags ({shared-id}) so anything you will MGET/MSET/transact/store together shares a slot; only the substring inside {} is hashed.
• Reserve multi-key commands and MULTI/EXEC for keys you have deliberately co-located; otherwise split into per-key operations and combine client-side.
• For Lua scripts, ensure every key passed in KEYS[] hashes to one slot (pass hash-tagged keys).
• Verify with CLUSTER KEYSLOT during design/testing, not in production.
• Keep the same-slot constraint in mind for RENAME, SMOVE, *STORE, and set/zset combinators — source and destination must co-locate.
• Use a cluster-aware client (-c / cluster mode) so single-key commands follow MOVED automatically; CROSSSLOT is the one thing the client cannot paper over.
• Drop the failing command into the free incident assistant, and see more Redis guides.

Quick Command Reference

# Are we in cluster mode?
redis-cli INFO cluster | grep cluster_enabled
redis-cli CLUSTER INFO | grep cluster_state

# Slot of each key
redis-cli -c CLUSTER KEYSLOT <key1>
redis-cli -c CLUSTER KEYSLOT <key2>

# Hash tag co-locates keys (only {..} is hashed)
redis-cli -c CLUSTER KEYSLOT '{user:42}:cart'
redis-cli -c CLUSTER KEYSLOT '{user:42}:total'

# Slot ownership map
redis-cli CLUSTER NODES | awk '{print $2,$9}'
redis-cli CLUSTER SLOTS

Conclusion

CROSSSLOT Keys in request don't hash to the same slot is a Redis Cluster constraint: a single multi-key command must touch keys that all live in the same hash slot. The typical situations are:

1. A multi-key command (MGET/MSET/DEL) across keys that hash to different slots.
2. Related keys named without a hash tag, so they scatter.
3. A MULTI/EXEC or Lua script whose keys span slots.
4. A *STORE/RENAME/SMOVE where source and destination differ.

The remedy is data modeling, not a Redis setting: put a {hash-tag} around the shared identifier so co-operated keys share a slot, and reserve multi-key operations for keys you have deliberately co-located. Verify with CLUSTER KEYSLOT before you ship.