Planned Valkey Switchovers Without Client Errors: CLIENT CAPA REDIRECT and FAILOVER

You need to patch the host under a standalone Valkey primary, so you promote a replica first, and the application still logs errors. Writes that reach the old primary after the role swap return READONLY You can't write against a read only replica. A BLPOP waiting on it returns UNBLOCKED and loses its connection. Valkey has two features that remove most of these errors. The FAILOVER command pauses writes, waits for the replica to catch up, and swaps roles. CLIENT CAPA redirect, added in Valkey 8.0, makes the demoted node answer -REDIRECT host:port, so the client can follow the new primary itself. This post covers how the two work together, which client libraries support the capability as of November 2026, what changed in Valkey 9.0 and the 9.2 release candidates, and a maintenance runbook.

Scope and review date: November 2026. This post covers self-managed Valkey 8.0 to 9.1.3 in standalone mode: one primary with replicas, with or without Sentinel. Behaviour from the 9.2 release candidates (newest: 9.2.0-rc2, 4 November 2026) is labelled as such. Commands, error strings, and client library behaviour were checked against the Valkey documentation, the Valkey 9.1.3 source, and each client library's repository on 10 November 2026. They were not run in a lab, so rehearse the runbook on staging.

What do clients see when a Valkey primary becomes a replica?

In standalone mode, a primary that turns into a replica keeps its client connections open, and nothing tells those clients that the role changed. With the default replica-read-only yes, three things follow for a client that has not declared any capability:

• Writes fail with -READONLY You can't write against a read only replica.
• Reads succeed, served by the demoted node, which now replicates from the new primary.
• Commands blocked on lists, sorted sets, or streams are released with -UNBLOCKED, and the server closes the connection after the reply.

# Which role does each node hold right now?
valkey-cli -h 10.0.0.11 -p 6379 ROLE
valkey-cli -h 10.0.0.12 -p 6379 ROLE

Interpretation: the first element of the reply is master or slave. Applications do not check the role before every command, so the error reply is usually their first sign. Without a redirect, they reach the new primary only after a DNS record, virtual IP, proxy, or Sentinel lookup changes.

How does the FAILOVER command switch a standalone primary?

FAILOVER dates from Redis 6.2.0 and is the standalone counterpart of CLUSTER FAILOVER. Per the FAILOVER command reference, the primary starts an internal CLIENT PAUSE WRITE, waits for a replica to acknowledge its whole replication offset, and demotes itself. It then sends PSYNC FAILOVER to the target, which promotes itself, and unpauses its clients. If the target refuses, the primary aborts and returns to normal; it keeps its data throughout.

The command takes three options. TO host port names the replica to wait for; without it, the primary fails over to the first replica that catches up. TIMEOUT milliseconds caps the time in waiting-for-sync and so caps the write outage. FORCE, which needs both TO and TIMEOUT, fails over to the target when the timeout expires instead of rolling back.

# Planned switchover to a named replica, with writes paused for at most 5 s
valkey-cli -h 10.0.0.11 -p 6379 FAILOVER TO 10.0.0.12 6379 TIMEOUT 5000

# Cancel it while the state is still waiting-for-sync
valkey-cli -h 10.0.0.11 -p 6379 FAILOVER ABORT

Interpretation: OK means the failover has started, not that it finished. A background task does the work, so you watch the state separately. The host and port must match the replica as the primary lists it in INFO replication: its replica-announce-ip or connection address, and its listening port.

The 9.1.3 source rejects a FAILOVER up front in these cases:

# Poll the failover state on the old primary
valkey-cli -h 10.0.0.11 -p 6379 INFO replication | grep -E '^(role|master_host|master_failover_state)'

Interpretation: master_failover_state moves from no-failover to waiting-for-sync to failover-in-progress, then back. Success means role:slave with master_host set to the target. A role:master line means it aborted, and the server log says why.

What does CLIENT PAUSE WRITE do to application traffic?

During waiting-for-sync, the primary holds writes; it does not reject them. The CLIENT PAUSE reference lists what else the WRITE mode holds: every EVAL and EVALSHA script, PUBLISH, PFCOUNT, and the acknowledgements for WAIT and WAITAOF. Plain reads keep running. Keys also stop expiring and being evicted during the pause, so the dataset is static while the replica catches up.

A held command occupies its connection, so pipelines and pools can stall behind it, and a client whose command timeout is shorter than the pause sees a timeout instead of a reply. The documentation says failovers typically take under a second, but longer under heavy writes or with a lagging replica. Set TIMEOUT below the shortest command timeout your clients use.

# Valkey 8.1 and later: is the node paused, and why?
valkey-cli -h 10.0.0.11 -p 6379 INFO clients | grep -E '^paused_'

Interpretation: during a FAILOVER, expect paused_reason:failover_in_progress and paused_actions:write. paused_reason:client_pause means a manual or Sentinel-issued CLIENT PAUSE is in force. These fields arrived in Valkey 8.1.0. The CLIENT PAUSE page still describes the older manual procedure (pause, wait a few seconds, promote); FAILOVER checks the replication offset instead of waiting a fixed time.

What does CLIENT CAPA redirect change for clients?

CLIENT CAPA arrived in Valkey 8.0.0 (GA on 15 September 2024, from PR #325). A client declares capabilities for its own connection, and the server ignores any it does not recognise; redirect is the only one today. On a standalone replica, a redirect-capable connection gets -REDIRECT primary-ip:port for every read and write command, and must send READONLY before it can read there. The address can be IPv6, so clients split host and port at the last colon. On a primary, the capability changes nothing until that primary is demoted.

# On the old primary after the switchover: find redirect-capable connections
valkey-cli -h 10.0.0.11 -p 6379 CLIENT LIST TYPE normal CAPA r

# Valkey 8.1: no CAPA filter yet, so search the capa field instead
valkey-cli -h 10.0.0.11 -p 6379 CLIENT LIST TYPE normal | grep -c 'capa=r'

Interpretation: CLIENT LIST shows a capa= field from Valkey 8.1, where r means redirect. The CAPA and NOT-CAPA filters arrived in 9.0. On 8.0 there is no way to list the capability, so check the client configuration instead.

In failover-in-progress, both nodes can be replicas for a moment, so a REDIRECT could bounce between them. Since 8.0.0-rc2 (PR #871), the old primary suspends redirect-capable clients during that phase and releases them once the target is promoted. Inside MULTI, a redirected command makes EXEC fail, so the client must replay the whole transaction on the new primary.

Which Valkey client libraries support CLIENT CAPA redirect?

Fewer than you might expect. The Valkey clients page badges four libraries with "Advanced capabilities" but describes the badge as handing off "slot redirections", which are MOVED and ASK. So we checked each library's source for the CLIENT CAPA redirect call and for -REDIRECT handling.

// valkey-go: standalone client that follows REDIRECT after a switchover
client, err := valkey.NewClient(valkey.ClientOption{
    InitAddress: []string{"10.0.0.11:6379"},
    Standalone:  valkey.StandaloneOption{EnableRedirect: true},
})

Interpretation: the client sends CLIENT CAPA redirect at connection setup. On a REDIRECT, it connects to the new primary and retries there. A new process still starts from InitAddress, so update that address after the switchover. The table reflects each library's default branch on 9 and 10 November 2026, checked against the named release; check the version you pin.

What happens to BLPOP and other blocked commands during a switchover?

Through Valkey 8.1, every client blocked on the primary was released with -UNBLOCKED force unblock from blocking operation, instance state changed (master -> replica?) when the node became a replica, and the server closed its connection. Valkey 9.0 changed this with PR #2329, shipped in 9.0.0-rc3 and GA on 21 October 2025.

• A redirect-capable client blocked on a list, sorted set, stream, or module key gets -REDIRECT host:port and keeps its connection.
• A client in READONLY mode that is blocked by a read command stays blocked through the switchover.
• Every other blocked client still gets -UNBLOCKED and is disconnected.
• In cluster mode, the equivalent case now returns -MOVED.

# A worker blocked on the old primary when FAILOVER completes
10.0.0.11:6379> CLIENT CAPA redirect
OK
10.0.0.11:6379> BLPOP jobs:email 0
(error) REDIRECT 10.0.0.12:6379

Interpretation: the BLPOP had not popped anything, so resending it to the new primary is safe. The PR is labelled client-changes-needed: the library must treat this REDIRECT as retryable. On 8.x, expect a dropped connection, and let the worker reconnect with backoff.

Where does REDIRECT still fall short?

Scripts are the main gap. Issue #868, still open, shows that a write inside EVAL on a replica returns READONLY even after CLIENT CAPA redirect. Its reproduction, quoted from the issue:

localhost:6380> client capa redirect
OK
localhost:6380> set foo bar
(error) REDIRECT redis:6379
localhost:6380> EVAL "return redis.call('SET', KEYS[1], ARGV[1])" 1 foo bar
(error) READONLY You can't write against a read only replica. script: d8f2fad9f8e86a53d2a6ebd960b33c4972cacc37, on @user_script:1.

Interpretation: a library that follows REDIRECT still needs a READONLY handler for scripts and functions. PR #1781 would fix scripts, WATCH, and keyless transactions, but it is still open as of November 2026.

The 9.2 release candidates change cluster mode. PR #3505 (in 9.2.0-rc1) makes cluster replicas redirect keyless commands such as SCAN, DBSIZE, and FLUSHDB for redirect-capable clients that have not sent READONLY, and is labelled breaking-change. Standalone mode decides on REDIRECT from command flags, not keys, so in our reading of the source it already redirected these. The valkey.io pages for CLIENT CAPA and READONLY already describe the 9.2 behaviour with no version switcher, so ignore the "Since Valkey 9.2" lines on 9.1.3.

How do you run a maintenance switchover step by step?

This runbook moves the primary from 10.0.0.11 to 10.0.0.12 so 10.0.0.11 can be patched, with a third node, 10.0.0.13, as a second replica. It assumes no Sentinel; the next section covers Sentinel.

The server log records each transition. These lines are taken from the log calls in the 9.1.3 source:

grep -E 'FAILOVER|Failover target|PRIMARY MODE' /var/log/valkey/valkey-server.log
# FAILOVER requested to 10.0.0.12:6379.
# Failover target 10.0.0.12:6379 is synced, failing over.
# FAILOVER to 10.0.0.12:6379 aborted: Replica never caught up before timeout

Interpretation: the first two lines appear on the old primary in a normal run, and the new primary logs PRIMARY MODE enabled when it accepts PSYNC FAILOVER. The third line means the replica missed the TIMEOUT and the old primary is still primary; find the lag before you retry. If configuration management owns valkey.conf, change it there instead of running CONFIG REWRITE, before the old primary restarts.

What changes when Sentinel manages the primary?

Do not run FAILOVER behind Sentinel's back. Sentinel still names the old primary, and in the 9.1.3 sentinel.c a primary that reports the replica role counts as unreachable, "so eventually a failover will be triggered", to a replica Sentinel picks.

From Valkey 9.0, Sentinel can do the planned version itself. The Sentinel documentation describes SENTINEL FAILOVER <primary name> COORDINATED: Sentinel wins a leader election and then "supervises an orderly handover using the FAILOVER command". It sends CLIENT PAUSE <ms> WRITE and FAILOVER TO ... TIMEOUT <ms> in one transaction, so the same write pause and offset check apply.

# Valkey 9.0 and later Sentinel: planned switchover for "mymaster"
valkey-cli -p 26379 SENTINEL FAILOVER mymaster COORDINATED

# Then confirm what Sentinel now reports as primary
valkey-cli -p 26379 SENTINEL GET-PRIMARY-ADDR-BY-NAME mymaster

Interpretation: the second command should return the promoted replica's address. Without COORDINATED, SENTINEL FAILOVER forces a failover "as if the primary was not reachable". Older Sentinels have only that mode.

Clients behave differently here. In our reading of sentinel.c, after the coordinated promotion Sentinel runs CLIENT KILL TYPE normal and CLIENT KILL TYPE pubsub on both nodes, then CLIENT UNPAUSE. So Sentinel clients mostly act on a dropped connection, not a REDIRECT, and must ask a Sentinel for the primary again. The Sentinel user also needs extra ACL permissions; Sentinel on Valkey 9: coordinated failover and the ACL change covers them.

Frequently asked questions

Key takeaways

Plan Valkey switchovers with JusDB

JusDB's Valkey high availability team can review your primary and replica topology, Sentinel configuration, and client library settings. We can also write and rehearse a switchover runbook with your engineers.

Bring your Valkey versions, the client libraries and versions each service uses, and your current failover procedure. Your team approves every production change.

Related reading

• Redis Sentinel vs Redis Cluster: choosing the right HA architecture
• Valkey performance tuning: memory, persistence, and cluster config
• Redis 8 vs Valkey 8 in production
• Valkey documentation: FAILOVER