CLUSTER-SETSLOT(3valkey)

📦

version 9.0.6 · 2 versions

9.0.6 · fedora 44 (latest)
8.1.10 · fedora 43

✨ CLUSTER-SETSLOT 💅

okay so this is CLUSTER-SETSLOT, from the Valkey Command Manual (the 3valkey girlies know) — and bestie, she's the one who binds a hash slot to a node. that's the whole job. let's get into it 🫶

📜 SYNOPSIS

CLUSTER SETSLOT slot <IMPORTING node-id | MIGRATING node-id | NODE
node-id | STABLE> [TIMEOUT timeout]

like… yes, that's a lot of angle brackets. breathe. we'll go one by one 💖

🌸 DESCRIPTION

CLUSTER SETSLOT is the one responsible for changing the state of a hash slot in the receiving node, in a bunch of different ways. it's part of the legacy mechanism for cluster resharding. so like, iconic but also, respectfully, old 💀

Note: for live resharding, the newer valkey-atomic-slot-migration(7) mechanism using CLUSTER MIGRATESLOTS is recommended — it's faster, more reliable, and has less impact on client applications. no cap. 🧚

depending on which subcommand you use, CLUSTER SETSLOT can:

MIGRATING subcommand: set a hash slot in migrating state.
IMPORTING subcommand: set a hash slot in importing state.
STABLE subcommand: clear any importing / migrating state from the hash slot.
NODE subcommand: bind the hash slot to a different node.

the command + its whole little subcommand family is useful for starting and ending cluster live resharding operations — which is accomplished by setting a hash slot in migrating state in the source node, and importing state in the destination node. two nodes, one slot, a whole journey 😭

each subcommand gets its own section below ⬇️ and at the end you'll find how live resharding is actually performed using this command and other related commands. sit down, get comfy, hydrate 💜

🦋 CLUSTER SETSLOT `<slot>` MIGRATING `<destination-node-id>`

this one sets a slot to migrating state. but to set a slot in this state, the node receiving the command must be the hash slot owner — otherwise an error is returned. periodt, no exceptions.

when a slot is in migrating state, the node changes behavior like this:

if a command is received about an existing key, the command is processed as usual.
if a command is received about a key that does not exist, an ASK redirection is emitted by the node, asking the client to retry only that specific query into destination-node. in this case the client should not update its hash slot to node mapping.
if the command contains multiple keys: if none exist, behavior is the same as point 2; if all exist, it's the same as point 1. but if only a partial number of keys exist, the command emits a TRYAGAIN error, so that the keys in question can finish being migrated to the target node and the multi-key command can actually run. it's giving "wait your turn bestie" ✋

🌈 CLUSTER SETSLOT `<slot>` IMPORTING `<source-node-id>`

this is the reverse of MIGRATING — it prepares the destination node to import keys from the specified source node. the command only works if the node is not already the owner of the specified hash slot. 🙈

when a slot is in importing state, the node changes behavior like this:

commands about this hash slot are refused and a MOVED redirection is generated as usual — except if the command follows an ASKING command, in which case the command is executed. 🫡

so when a node in migrating state generates an ASK redirection, the client contacts the target node, sends ASKING, and immediately after sends the command. this way, commands about non-existing keys in the old node (or keys already migrated to the target node) get executed in the target node, so that:

new keys are always created in the target node. during a hash slot migration we only have to move old keys, not new ones. efficiency slay 💅
commands about keys already migrated are correctly processed in the context of the node which is the target of the migration — the new hash slot owner — in order to guarantee consistency.
without ASKING the behavior is the same as usual. this guarantees that clients with a broken hash slots mapping will not write by mistake in the target node, creating a new version of a key that has yet to be migrated. protecting you from yourself, respectfully 🛡️

🎀 CLUSTER SETSLOT `<slot>` STABLE

this subcommand just clears migrating / importing state from the slot. it's mainly used to fix a cluster stuck in a wrong state via valkey-cli --cluster fix. normally though, the two states get cleared automatically at the end of the migration using the SETSLOT ... NODE ... subcommand — as explained in the next section. so this is the "emergency reset button" vibe ⭐

👑 CLUSTER SETSLOT `<slot>` NODE `<node-id>`

okay this one has the most complex semantics. it associates the hash slot with the specified node — but the command only works in specific situations and has different side effects depending on the slot state. here's the full set of pre-conditions and side effects:

if the current hash slot owner is the node receiving the command, but because of the command the slot would be assigned to a different node, the command will return an error if there are still keys for that hash slot in the node receiving the command. 🚨
if the slot is in migrating state, that state gets cleared when the slot is assigned to another node.
if the slot was in importing state in the node receiving the command, and the command assigns the slot to this node (which is what happens in the target node at the end of the resharding of a hash slot from one node to another), the command has these side effects:
- A) the importing state is cleared.
- B) if the node config epoch is not already the greatest of the cluster, it generates a new one and assigns the new config epoch to itself. this way its new hash slot ownership will win over any past configuration created by previous failovers or slot migrations. main character energy, honestly 👑

important: step 3 is the only time when a Valkey Cluster node will create a new config epoch without agreement from other nodes. this only happens when a manual configuration is operated. however, it is impossible for this to create a non-transient setup where two nodes have the same config epoch, since Valkey Cluster uses a config epoch collision resolution algorithm. so like… chaotic but it's handled 💖

🧚 Valkey Cluster live resharding explained

CLUSTER SETSLOT is an important piece used by Valkey Cluster in order to migrate all the keys contained in one hash slot from one node to another. here's how the migration is orchestrated, with the help of other commands too. we'll call the node that has the current ownership of the hash slot the source node, and the node where we want to migrate the destination node.

set the destination node slot to importing state using CLUSTER SETSLOT <slot> IMPORTING <source-node-id>.
set the source node slot to migrating state using CLUSTER SETSLOT <slot> MIGRATING <destination-node-id>.
get keys from the source node with the valkey-cluster-getkeysinslot(7) CLUSTER GETKEYSINSLOT command and move them into the destination node using the valkey-migrate(7) MIGRATE command.
send CLUSTER SETSLOT <slot> NODE <destination-node-id> to the destination node.
send CLUSTER SETSLOT <slot> NODE <destination-node-id> to the source node.
send CLUSTER SETSLOT <slot> NODE <destination-node-id> to the other primary nodes (optional).

Notes:

the order of step 1 and 2 is important. we want the destination node to be ready to accept ASK redirections when the source node is configured to redirect. 🔁
the order of step 4 and 5 is important. the destination node is responsible for propagating the change to the rest of the cluster. if the source node is informed before the destination node and the destination node crashes before it's set as new slot owner, the slot is left with no owner, even after a successful failover. 💀 do not do this.
step 6 — sending SETSLOT to the nodes not involved in the resharding — is not technically necessary since the configuration will eventually propagate itself. however, it's a good idea to do it anyway, in order to stop nodes from pointing to the wrong node for the hash slot that moved as soon as possible, resulting in fewer redirections to find the right node. be nice to your clients 🥺
starting from Valkey 8.0, CLUSTER SETSLOT is synchronously replicated to all healthy replicas running Valkey version 8.0+. by default, this synchronous replication must complete within 2 seconds. if the replication fails, the primary does not execute the command, and the client receives a NOREPLICAS Not enough good replicas to write error. operators can retry the command or customize the timeout using the TIMEOUT parameter to further increase the reliability of live reconfiguration:

CLUSTER SETSLOT slot [MIGRATING|IMPORTING|NODE] node-id [TIMEOUT timeout]

here, timeout is measured in seconds, with 0 meaning to wait indefinitely. ✨

💌 REPLY

valkey-protocol(7) Simple string reply: all the sub-commands return OK if the command was successful. otherwise an error is returned.

⚡ COMPLEXITY

O(1) — constant time, we love a fast queen 🏃♀️💨

🔐 ACL CATEGORIES

@admin @dangerous @slow

(yes, @dangerous. respect the warning bestie, this one rearranges your whole cluster's sense of self 🔥)

🕰️ HISTORY

Available since: 3.0.0
Changed in 8.0.0: Added the TIMEOUT option.

that's the whole page bestie, you ate it 🍓💅 ok and for the little sign-off moment: this was from Valkey 9.0.0, dated 2025-10-21, and yes — the whole thing is the CLUSTER-SETSLOT(3valkey) manual. go forth and reshard responsibly 🌈👑✨

📦 where this page comes from

fedora 44: valkey-doc 9.0.3-2.fc44 · CC-BY-SA-4.0
fedora 44: valkey-doc 9.0.6-1.fc44 · CC-BY-SA-4.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms