CLUSTER-FORGET(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ CLUSTER-FORGET ✨

okay so bestie, this is cluster-forget from the valkey command manual (3valkey), and it does exactly what it says on the tin: it removes a node from the nodes table. simple concept, kinda chaotic execution. let's get into it 💅

🌸 SYNOPSIS 🌸

CLUSTER FORGET node-id

💖 DESCRIPTION 💖

so the whole vibe here is: you wanna remove a node — you specify it by its node ID — and it gets yeeted out of the set of known nodes of the Valkey Cluster node that received the command. in other words, the node you named is removed from the nodes table of whoever got the command. periodt.

and here's the thing bestie, because when a node is part of the cluster, all the other nodes participating in the cluster know about it. so for a node to be completely removed from a cluster, the CLUSTER FORGET command has to be sent to all the remaining nodes, and idc whether they're primaries or replicas, they all gotta hear it. no exceptions 🫶

but wait, it gets deeper. the command can't just simply drop the node from the internal node table of whoever received it. it also implements a ban-list, which stops that same node from being added right back in as a side effect of processing the gossip section of the heartbeat packets coming in from other nodes. like, it's giving "you can't sit with us" energy.

🍓 Details on why the ban-list is needed

okay so let me show you why the command must not just remove a node from the nodes table but ALSO prevent it from being re-inserted again for some time. buckle up.

let's assume we have four nodes: A, B, C and D. to end up with just a three node cluster A, B, C we may follow these steps:

  1. Reshard all the hash slots from D to nodes A, B, C.
  2. D is now empty, but still listed in the nodes table of A, B and C.
  3. We contact A, and send CLUSTER FORGET D.
  4. B sends node A a heartbeat packet, where node D is listed.
  5. A does no longer known node D (see step 3), so it starts a handshake with D.
  6. D ends re-added in the nodes table of A.

see how fragile that is?? 😭 removing a node this way is so precarious — we'd need to send CLUSTER FORGET commands to all the nodes ASAP, just hoping there's no gossip section processing happening in the meantime. and because of this whole problem, the command implements a ban-list with an expire time for each entry. iconic behavior honestly.

so what the command really does is:

  1. The specified node gets removed from the nodes table.
  2. The node ID of the removed node gets added to the ban-list, for 1 minute.
  3. The node will skip all the node IDs listed in the ban-list when processing gossip sections received in heartbeat packets from other nodes.

which means we get a 60 second window to inform all the nodes in the cluster that we want to remove a node. sixty seconds bestie, use them wisely ⏳✨

🦋 Special conditions not allowing the command execution

the command does NOT succeed and returns an error in these cases:

  1. The specified node ID is not found in the nodes table.
  2. The node receiving the command is a replica, and the specified node ID identifies its current primary.
  3. The node ID identifies the same node we are sending the command to.

🎀 REPLY 🎀

valkey-protocol(7) Simple string reply: OK if the command was executed successfully. otherwise an error is returned. so either it's slay or it's a no 💀

⭐ COMPLEXITY ⭐

O(1) — constant time, we love a low-effort queen 👑

👑 ACL CATEGORIES 👑

@admin @dangerous @slow

note the @dangerous tag bestie. this one is not playing around 🙈

🌈 HISTORY 🌈

  • Available since: 3.0.0

💜 SEE ALSO 💜

asking(3valkey), cluster(3valkey), cluster-addslots(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-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 was 3valkey version 9.0.0, dated 2025-10-21, and honestly it ate. go forth and forget some nodes, but like, responsibly 💖✨🦋🌸💅🫶

📦 where this page comes from