FAILOVER(3valkey)

📦

version 9.0.6 · 2 versions

9.0.6 · fedora 44 (latest)
8.1.10 · fedora 43

👑 FAILOVER 💅

okay bestie, welcome to the Valkey Command Manual — this one's FAILOVER, and it's giving main character energy. it's a (3valkey) page, so buckle up 🎀

✨ NAME ✨

failover — starts a coordinated failover from a server to one of its replicas. yes, we're handing the crown to somebody else. iconic behavior, honestly 👑

🌸 SYNOPSIS 🌸

FAILOVER [TO host port [FORCE]] [ABORT] [TIMEOUT milliseconds]

💖 DESCRIPTION 💖

okay so here's the tea. this command kicks off a coordinated failover between the primary you're currently connected to and one of its replicas. it is not synchronous — instead a background task does the actual coordinating. the whole point is to limit data loss and limit how unavailable the cluster gets during the switch. it's basically the same vibe as the valkey-cluster-failover(7) CLUSTER FAILOVER command, but for non-clustered Valkey, and it's similar to the failover support sentinel gives you. slay 🌈

so the default failover flow goes a little something like this:

the primary internally starts a valkey-client-pause(7) CLIENT PAUSE WRITE, which pauses incoming writes and stops new data from piling up in the replication stream. no new drama allowed 💅
the primary monitors its replicas, waiting for one of them to say it has fully consumed the replication stream. if the primary has multiple replicas, it only waits for the first replica to catch up.
the primary then demotes itself to a replica. this is done to prevent any dual primary scenarios. NOTE: the primary does not discard its data, so it can still rollback if the replica rejects the failover request in the next step. safety net, bestie 🫶
the previous primary sends a special PSYNC request to the target replica — valkey-psync(7) PSYNC FAILOVER — telling the target replica to become a primary. glow up time 👑
once the previous primary gets acknowledgement that the PSYNC FAILOVER was accepted, it unpauses its clients. if the PSYNC request is rejected, the primary aborts the failover and goes back to normal. no harm no foul 😌

the field master_failover_state in valkey-info(7) INFO replication can be used to track the current state of the failover. it has these values:

no-failover: there is no ongoing coordinated failover.
waiting-for-sync: the primary is waiting for the replica to catch up to its replication offset.
failover-in-progress: the primary has demoted itself, and is attempting to hand off ownership to a target replica.

NOTE: during the failover-in-progress phase, the primary first demotes itself to a replica and then notifies the replica to promote itself to primary. these two steps are an asynchronous process, which may result in the simultaneous existence of two nodes as replicas 😭. in this scenario, for clients that support REDIRECT (that means explicitly executing valkey-client-capa(7) CLIENT CAPA REDIRECT), the redirection result may bounce back and forth between the two replicas until the target replica completes the process of promoting itself to primary. to avoid this situation, during the failover-in-progress phase, we temporarily suspend the clients that need to be redirected until the replica truly becomes the primary, and then resume the execution. problem solved, periodt ✨

if the previous primary had additional replicas attached to it, they will continue replicating from it as chained replicas. you will need to manually execute a valkey-replicaof(7) REPLICAOF on these replicas to start replicating directly from the new primary. manual labor, unfortunately 🥲

🎀 Optional arguments 🎀

the following optional arguments exist to modify the behavior of the failover flow:

TIMEOUT milliseconds — this option lets you specify a maximum time a primary will wait in the waiting-for-sync state before aborting the failover attempt and rolling back. it's meant to set an upper bound on the write outage the Valkey cluster can experience. failovers typically happen in less than a second, but could take longer if there's a large amount of write traffic or the replica is already behind in consuming the replication stream. if this value is not specified, the timeout can be considered to be "infinite". no cap, infinite ♾️
TO HOST PORT — this option lets you designate a specific replica, by its host and port, to failover to. the primary will wait specifically for this replica to catch up to its replication offset, and then failover to it. picking your fave, we love that for you 💜
FORCE — if both the TIMEOUT and TO options are set, the force flag can also be used to designate that once the timeout has elapsed, the primary should failover to the target replica instead of rolling back. this can be used for a best-effort attempt at a failover without data loss, but limiting write outage.

NOTE: the primary will always rollback if the PSYNC FAILOVER request is rejected by the target replica. that part is not negotiable bestie.

🦋 Failover abort 🦋

the failover command is intended to be safe from data loss and corruption, but it can encounter some scenarios it can not automatically remediate from and may get stuck 💀. for this purpose, the FAILOVER ABORT command exists, which will abort an ongoing failover and return the primary to its normal state. the command has no side effects if issued in the waiting-for-sync state, but it can introduce multi-primary scenarios in the failover-in-progress state. if a multi-primary scenario is encountered, you will need to manually identify which primary has the latest data and designate it as the primary and have the other replicas. (yes, that's how the original says it — go figure which one's the real one 👀)

NOTE: valkey-replicaof(7) REPLICAOF is disabled while a failover is in progress. this is to prevent unintended interactions with the failover that might cause data loss. hands off the wheel while the car's switching drivers 🚗

💌 REPLY 💌

valkey-protocol(7) Simple string reply: OK if the command was accepted and a coordinated failover is in progress. an error if the operation cannot be executed.

⚡ COMPLEXITY ⚡

O(1) — constant time, she's efficient 💅

🔐 ACL CATEGORIES 🔐

@admin @dangerous @slow

she's tagged @dangerous for a reason bestie. this is not a casual lil command. respect the crown 👑

📜 HISTORY 📜

available since: 6.2.0

aaaand that's the whole page bestie 💖 this one's from Valkey 9.0.0, dated 2025-10-21. go forth and failover responsibly, mwah 🫶✨

📦 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