CLUSTER-ADDSLOTS(3valkey)

✨ CLUSTER-ADDSLOTS ✨

okay bestie, so this is a page from the Valkey Command Manual (the 3valkey girlies) and it's all about handing out hash slots like they're friendship bracelets 💖

🌸 NAME 🌸

cluster-addslots — Assigns new hash slots to a node.

🎀 SYNOPSIS 🎀

CLUSTER ADDSLOTS slot [slot...]

💅 DESCRIPTION 💅

So like, this command is the glow-up tool for changing how a node sees the cluster config. Concretely? It hands a whole set of hash slots to whichever node got the command. And if it works, that node maps those slots to itself and starts broadcasting the new config to everybody. main character behavior, honestly 👑

But like… there are receipts. Read these:

1. The command only works if all the specified slots are, from the point of view of the node receiving the command, currently not assigned. A node will straight up refuse to take ownership of slots that already belong to some other node (and yes, that includes itself — no take-backs, no double-dipping 🙅♀️).
2. The command fails if the same slot is specified multiple times. Don't be messy.
3. Side effect alert 🚨 — if a slot among the ones you passed as an argument is set as importing, that state gets cleared once the node assigns the (previously unbound) slot to itself.

---

💬 REPLY 💬

valkey-protocol(7) Simple string reply: OK if the command was successful. Otherwise an error is returned. 😭

---

🧮 COMPLEXITY 🧮

O(N) where N is the total number of hash slot arguments.

---

👑 ACL CATEGORIES 👑

@admin @dangerous @slow

---

📜 HISTORY 📜

• Available since: 3.0.0

🌈 Example 🌈

So like, this next command assigns slots 1 2 3 to the node receiving the command:

> CLUSTER ADDSLOTS 1 2 3
OK

But trying to run it again? Error city, because the slots are already assigned:

> CLUSTER ADDSLOTS 1 2 3
ERR Slot 1 is already busy

🧚 Usage in Valkey Cluster 🧚

This command only works in cluster mode, and it's useful in these Valkey Cluster operations:

1. To create a new cluster — ADDSLOTS is used in order to initially setup primary nodes splitting the available hash slots among them.
2. In order to fix a broken cluster where certain slots are unassigned.

🦋 Information about slots propagation and warnings 🦋

ok so heads up: once a node assigns a set of slots to itself, it will start propagating this information in heartbeat packet headers. However — the other nodes will accept the information only if they have the slot as not already bound with another node, or if the configuration epoch of the node advertising the new hash slot, is greater than the node currently listed in the table.

Which means 👀 this command should be used with care only by applications orchestrating Valkey Cluster, like valkey-cli, and the command if used out of the right context can leave the cluster in a wrong state or cause data loss. Like. That's not a vibe. Do not do that. 💀

---

🔗 SEE ALSO 🔗

asking(3valkey), cluster(3valkey), cluster-addslotsrange(3valkey), cluster-bumpepoch(3valkey), cluster-cancelslotmigrations(3valkey), cluster-count-failure-reports(3valkey), cluster-countkeysinslot(3valkey), cluster-delslots(3valkey), cluster-delslotsrange(3valkey), cluster-failover(3valkey), cluster-flushslots(3valkey), cluster-forget(3valkey), cluster-getkeysinslot(3valkey), cluster-getslotmigrations(3valkey), cluster-help(3valkey), cluster-info(3valkey), cluster-keyslot(3valkey), cluster-links(3valkey), cluster-meet(3valkey), cluster-migrateslots(3valkey), cluster-myid(3valkey), cluster-myshardid(3valkey), cluster-nodes(3valkey), cluster-replicas(3valkey), cluster-replicate(3valkey), cluster-reset(3valkey), cluster-saveconfig(3valkey), cluster-set-config-epoch(3valkey), cluster-setslot(3valkey), cluster-shards(3valkey), cluster-slot-stats(3valkey), cluster-slots(3valkey), cluster-syncslots(3valkey), readonly(3valkey), readwrite(3valkey)

---

and that's the whole page, bestie!! 🫶 this one's from the 9.0.0 era, dated 2025-10-21, and it's giving CLUSTER-ADDSLOTS(3valkey) energy. go assign those slots responsibly, slay, periodt 💜✨