Hash Slot Calculator for Redis and Valkey Clusters

Find which slot of a Redis or Valkey cluster a key lands in, and which primary holds it. Check a multi-key command for CROSSSLOT errors before your code sends it, and see how a whole list of keys spreads across the cluster. It all runs in your browser.

Nothing you paste leaves this page. The tool doesn’t send anything anywhere, and the page’s security policy stops it from fetching or loading anything from another site, so your keys and cluster layout stay on your machine.

On a wide screen you can open it full screen.

How to Use It

  1. Find a key’s slot. Type a key. You get its slot, the primary that holds it, and the key with the hashed part marked.
  2. Check a command. Paste a command such as MSET user:{42}:name Ana user:{42}:plan pro. The tool picks out the keys the way the server does and says whether a cluster would run it or answer CROSSSLOT.
  3. See how many keys spread. Paste a key list or load a file, one key per line. You get the keys per primary, the busiest slots, the most used hash tags and every key’s slot, which you can download as CSV.
  4. Set the cluster layout. By default the tool assumes a new cluster of three primaries, split the way --cluster create splits it. Change the number, or paste the output of CLUSTER NODES from your own cluster.

To list a server’s keys without slowing it down, use --scan and never KEYS *:

redis-cli -h 10.0.0.4 -p 6379 --scan > keys.txt

How Hash Slots Work

A cluster doesn’t place keys one by one. It splits the key space into 16,384 slots and gives each primary a range of them. A key’s slot comes from a checksum: the server runs CRC16 over the key and keeps the last 14 bits, a number from 0 to 16383. So somekey is in slot 11058 on every cluster in the world. Which primary holds slot 11058 depends on your cluster.

A command that touches several keys only runs when they’re all in one slot. That’s where hash tags come in. If a key holds a part in braces, such as user:{42}:name, only that part is hashed, so user:{42}:name and user:{42}:plan share a slot. Only the first { and the first } after it count, and empty braces don’t count at all. A tag shared by too many keys puts them all on one primary, and the tool flags that too.

How It Was Tested

The tool was checked against real servers, Valkey 9.1.2 and Redis 8.10.2, built from source:

  • 10,029 keys, from plain text to raw binary, landed in the same slot as the servers’ CLUSTER KEYSLOT gave them.
  • For 868 commands on Valkey and 924 on Redis, covering every multi-key command that takes keys, the tool picked out the same keys as the servers’ COMMAND GETKEYS. That includes awkward cases such as SORT with GET, LIMIT and two STOREs.
  • 686 multi-key commands sent to a live Valkey cluster and 742 to a Redis cluster got the CROSSSLOT answer the tool predicted, with one exception, below.
  • Shard channels were checked on the clusters too. Valkey 9.1.2 places them in slots like keys. Redis 8.10.2 does for SSUBSCRIBE but runs SUNSUBSCRIBE on any node, and the tool notes the difference.

The exception is MSETEX, new in Valkey 9.1 and Redis 8.4. Redis refuses it across slots. Valkey 9.1.2 ran all 9 cross-slot MSETEX commands it was sent, and wrote every key on whichever node received the command, even keys whose slots belong to another node, where a later GET can’t find them. The tool adds a note to every MSETEX it checks. The manual has the transcript.

The Code

The calculator’s logic is one JavaScript file with no dependencies, open source under the Apache License 2.0. It runs as this page, as a command line in Node.js, and inside your own code:

node slots/cli.js --check 'MGET a b c'
redis-cli --scan | node slots/cli.js --file - --nodes nodes.txt --summary

The full manual, the tests and the recorded server answers are in the slots folder on GitHub. The other tools work the same way.