{
  "schema_version": 2,
  "id": "commands/cluster-forget",
  "title": "CLUSTER FORGET",
  "url": "https://redis.io/docs/latest/commands/cluster-forget/",
  "summary": "Removes a node from the nodes table.",
  "since": "3.0.0",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-06-15T06:26:34-07:00",
  "page_type": "content",
  "content_hash": "023476ed6b3d11856a344f06158b984117a0e661aabaa6ae9f20a36596b00664",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "The command is used to remove a node, specified by its node ID,\nfrom the set of known nodes of the Redis Cluster node receiving the command.\nIn other words, the specified node is removed from the nodes table of the\nnode receiving the command.\n\nBecause when a given node is part of the cluster, all the other nodes\nparticipating in the cluster knows about it, in order for a node to be\ncompletely removed from a cluster, the `CLUSTER FORGET` command must be\nsent to all the remaining nodes, regardless of the fact they are masters\nor replicas.\n\nHowever, the command cannot simply drop the node from the internal node\ntable of the node receiving the command, it also implements a ban list, not\nallowing the same node to be added again as a side effect of processing the\ngossip section of the heartbeat packets received from other nodes.\n\nStarting with Redis 7.2.0, the ban list is included in cluster gossip ping/pong messages. \nThis means that `CLUSTER FORGET` doesn't need to be sent to all nodes in a cluster.\nYou can run the command on one or more nodes, after which it will be propagated to the rest of the nodes in most cases."
    },
    {
      "id": "required-arguments",
      "title": "Required arguments",
      "role": "content",
      "text": "<details open><summary><code>node-id</code></summary>\n\nThe ID of the node to remove from the current node's view of the cluster.\n\n</details>"
    },
    {
      "id": "details",
      "title": "Details",
      "role": "content",
      "text": ""
    },
    {
      "id": "details-on-why-the-ban-list-is-needed",
      "title": "Details on why the ban list is needed",
      "role": "content",
      "text": "In the following example we'll show why the command must not just remove\na given node from the nodes table, but also prevent it for being re-inserted\nagain for some time.\n\nLet's assume we have four nodes, A, B, C and D. In order to\nend with just a three nodes cluster A, B, C we may follow these steps:\n\n1. Reshard all the hash slots from D to nodes A, B, C.\n2. D is now empty, but still listed in the nodes table of A, B and C.\n3. We contact A, and send `CLUSTER FORGET D`.\n4. B sends node A a heartbeat packet, where node D is listed.\n5. A does no longer known node D (see step 3), so it starts a handshake with D.\n6. D ends re-added in the nodes table of A.\n\nAs you can see in this way removing a node is fragile, we need to send\n`CLUSTER FORGET` commands to all the nodes ASAP hoping there are no\ngossip sections processing in the meantime. Because of this problem the\ncommand implements a ban list with an expire time for each entry.\n\nSo what the command really does is:\n\n1. The specified node gets removed from the nodes table.\n2. The node ID of the removed node gets added to the ban list, for 1 minute.\n3. The node will skip all the node IDs listed in the ban list when processing gossip sections received in heartbeat packets from other nodes.\n\nThis way we have a 60 second window to inform all the nodes in the cluster that\nwe want to remove a node."
    },
    {
      "id": "special-conditions-not-allowing-the-command-execution",
      "title": "Special conditions not allowing the command execution",
      "role": "content",
      "text": "The command does not succeed and returns an error in the following cases:\n\n1. The specified node ID is not found in the nodes table.\n2. The node receiving the command is a replica, and the specified node ID identifies its current master.\n3. The node ID identifies the same node we are sending the command to."
    },
    {
      "id": "redis-software-and-redis-cloud-compatibility",
      "title": "Redis Software and Redis Cloud compatibility",
      "role": "content",
      "text": "| Redis<br />Software | Redis<br />Cloud | <span style=\"min-width: 9em; display: table-cell\">Notes</span> |\n|:----------------------|:-----------------|:------|\n| <span title=\"Not supported\">&#x274c; Standard</span><br /><span title=\"Not supported\"><nobr>&#x274c; Active-Active</nobr></span> | <span title=\"Not supported\">&#x274c; Standard</span><br /><span title=\"Not supported\"><nobr>&#x274c; Active-Active</nobr></span> |  |"
    },
    {
      "id": "return-information",
      "title": "Return information",
      "role": "returns",
      "text": "**RESP2:**\n\n[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was executed successfully. Otherwise an error is returned.\n\n**RESP3:**\n\n[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was executed successfully. Otherwise an error is returned."
    }
  ],
  "examples": []
}