Fix the CROSSSLOT Keys error in Redis cluster-mode enabled with clear examples, hash-slot details, and working code snippets. Our Live Support team is always here to help you.

Fixing the CROSSSLOT Keys Error in Redis Cluster-Mode Enabled

Running into the CROSSSLOT Keys error in Redis cluster-mode enabled can be frustrating, especially after switching from a single Redis server to a clustered setup. This issue pops up when multi-key commands span across different hash slots, but the fix is simpler than it looks.

CROSSSLOT Keys in request don’t hash to the same slot

If you’ve faced the same issue after enabling cluster mode, here’s a clear explanation and practical fix without dragging into theory more than needed.

Where Does This Error Come From?

In cluster mode, Redis no longer stores everything in a single instance. Instead, data is distributed across multiple nodes. This distribution is managed using hash slots. While this enables horizontal scalability, it also brings restrictions on multi-key commands.

The error message points to this restriction:

“Keys in request don’t hash to the same slot.”

This happens because the command is trying to access multiple keys that belong to different hash slots, which the cluster cannot process in one go.

What is a Hash Slot in Redis?

Redis Cluster uses a hashing algorithm to assign each key to a slot. Each key gets an integer hash-slot, and keys with the same slot will be stored on the same node.

You can check this yourself by connecting to your Redis cluster:

redis-cli -h [CLUSTER_ADDRESS] -p 6379

Now create two keys and check their assigned slots:

redis> SET mykey1 "Hello"

"OK"

redis> SET mykey2 "Hello 2"

"OK"

redis> CLUSTER KEYSLOT mykey1

(integer) 650

redis> CLUSTER KEYSLOT mykey2

(integer) 8734

As shown, both keys are in different slots and most likely on different nodes.

Why Does the CROSSSLOT Error Occur?

When you run a command that involves multiple keys, Redis expects those keys to be in the same slot. If not, the operation is rejected with the CROSSSLOT Keys error.

Example:

redis> SUNION mykey1 mykey2

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

How to Solve CROSSSLOT Error at the Application Level

The solution is to use hashtags to control key distribution. Redis allows you to wrap part of the key name inside curly braces {…}. Only the substring inside braces is used to calculate the hash slot. This way, multiple keys can be forced into the same slot.

For instance:

redis> CLUSTER KEYSLOT {user1}:mykey1

(integer) 8006

redis> CLUSTER KEYSLOT {user1}:mykey2

(integer) 8006

Now both keys share the same hash slot. Running multi-key operations works without errors:

redis> SUNION {user1}:mykey1 {user1}:mykey2

1) "Hello"

2) "Hello 2"

Almost all Redis clients support this tagging feature, so check your library documentation for usage.

Conclusion

The CROSSSLOT Keys error in Redis cluster-mode enabled is not a bug, but a design safeguard to maintain consistency across nodes. By grouping related keys with hashtags, you avoid the restriction and continue using multi-key operations as intended.

If your application relies on multi-key commands, plan your key structure carefully before scaling into Redis cluster mode.