# CLUSTER FAILOVER

```json metadata
{
  "schema_version": 2,
  "title": "CLUSTER FAILOVER",
  "description": "Forces a replica to perform a manual failover of its master.",
  "categories": ["docs","develop","stack","oss","rs","rc","oss","kubernetes","clients"],
  "arguments": [{"arguments":[{"display_text":"force","name":"force","token":"FORCE","type":"pure-token"},{"display_text":"takeover","name":"takeover","token":"TAKEOVER","type":"pure-token"}],"name":"options","optional":true,"type":"oneof"}],
  "syntax_fmt": "CLUSTER FAILOVER [FORCE | TAKEOVER]",
  "complexity": "O(1)",
  "group": "cluster",
  "command_flags": ["admin","stale","no_async_loading"],
  "acl_categories": ["@admin","@slow","@dangerous"],
  "since": "3.0.0",
  "arity": -2,
  "tableOfContents": {"sections":[{"id":"optional-arguments","title":"Optional arguments"},{"children":[{"id":"manual-failover-when-the-primary-is-down","title":"Manual failover when the primary is down"},{"id":"manual-failover-without-cluster-consensus","title":"Manual failover without cluster consensus"},{"id":"implementation-details-and-notes","title":"Implementation details and notes"}],"id":"details","title":"Details"},{"id":"redis-software-and-redis-cloud-compatibility","title":"Redis Software and Redis Cloud compatibility"},{"id":"return-information","title":"Return information"}]}

,
  "codeExamples": []
}
```

This command, which can only be sent to a Redis Cluster replica node, forces
the replica to start a manual failover of its primary instance.

Use a manual failover when you want to replace the current primary with one of its replicas, even though the primary has not failed. Send the command to the replica that you want to promote. Redis Cluster performs the failover safely and avoids data loss by making sure the replica has processed the primary’s full replication stream before it takes over.

A manual failover works as follows:

1. The replica tells the primary to stop processing client requests.1. The primary sends its current replication offset to the replica.
1. The replica waits until it reaches the same replication offset, which confirms that it has processed all data from the primary.
1. The replica starts the failover, gets a new configuration epoch from a majority of primary nodes, and broadcasts the new configuration.
1. The old primary receives the configuration update, unblocks its clients, and starts returning redirection messages so clients connect to the new primary.

This process moves clients from the old primary to the new primary only after the new primary has processed the full replication stream.

## Optional arguments

<details open><summary><code>FORCE | TAKEOVER</code></summary>

`FORCE` starts the failover without coordinating with the primary, for use when the primary is unreachable. `TAKEOVER` additionally bypasses the cluster consensus needed to authorize the failover.

</details>

## Details

### Manual failover when the primary is down

The command behavior can be modified by two options: `FORCE` and `TAKEOVER`.

If the `FORCE` option is given, the replica does not perform any handshake
with the primary, that may be not reachable, but instead just starts a
failover starting from point 4 above. This is useful when you want to start
a manual failover while the primray is no longer reachable.

However, using `FORCE` requires that the majority of primaries are available
to authorize the failover and generate a new configuration epoch
for the replica that is going to become primary.

### Manual failover without cluster consensus

There are situations where this is not enough, and you want a replica to failover
without any agreement with the rest of the cluster. A real world use case
for this is to mass promote replicas in a different data center to primaries
in order to perform a data center switch, while all the primaries are down
or partitioned away.

The `TAKEOVER` option implies everything `FORCE` implies, but also does
not use any cluster authorization in order to failover. A replica receiving
`CLUSTER FAILOVER TAKEOVER` will instead:

1. Generate a new `configEpoch` unilaterally, just taking the current greatest epoch available and incrementing it if its local configuration epoch is not already the greatest.
2. Assign itself all the hash slots of its primary, and propagate the new configuration to every node which is reachable ASAP, and eventually to every other node.

Note that `TAKEOVER` violates the last-failover-wins principle of Redis Cluster, since the configuration epoch generated by the replica violates the normal generation of configuration epochs in several ways:

1. There is no guarantee that it is actually the higher configuration epoch, since, for example, we can use the `TAKEOVER` option within a minority, nor any message exchange is performed to generate the new configuration epoch.
2. If we generate a configuration epoch which happens to collide with another instance, eventually our configuration epoch, or the one of another instance with our same epoch, will be moved away using the *configuration epoch collision resolution algorithm*.

Because of this the `TAKEOVER` option should be used with care.

### Implementation details and notes

* `CLUSTER FAILOVER`, unless the `TAKEOVER` option is specified, does not execute a failover synchronously.
  It only schedules a manual failover, bypassing the failure detection stage.
* An `OK` reply is no guarantee that the failover will succeed.
* A replica can only be promoted to a primary if it is known as a replica by a majority of the primaries in the cluster.
  If the replica is a new node that has just been added to the cluster (for example after upgrading it), it may not yet be known to all the primaries in the cluster.
  To check that the primaries are aware of a new replica, you can send [`CLUSTER NODES`](https://redis.io/docs/latest/commands/cluster-nodes) or [`CLUSTER REPLICAS`](https://redis.io/docs/latest/commands/cluster-replicas) to each of the primary nodes and check that it appears as a replica, before sending `CLUSTER FAILOVER` to the replica.
* To check that the failover has actually happened you can use [`ROLE`](https://redis.io/docs/latest/commands/role), `INFO REPLICATION` (which indicates "role:master" after successful failover), or [`CLUSTER NODES`](https://redis.io/docs/latest/commands/cluster-nodes) to verify that the state of the cluster has changed sometime after the command was sent.
* To check if the failover has failed, check the replica's log for `Manual failover timed out`, which is logged if the replica has given up after a few seconds.

## Redis Software and Redis Cloud compatibility

| Redis<br />Software | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
|:----------------------|:-----------------|:------|
| <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> |  |

## Return information

**RESP2:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was accepted and a manual failover is going to be attempted. An error if the operation cannot be executed, for example if the client is connected to a node that is already a primary.

**RESP3:**

[Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` if the command was accepted and a manual failover is going to be attempted. An error if the operation cannot be executed, for example if the client is connected to a node that is already a primary.