Redis: MASTERDOWN Link with MASTER is down

What it means

A replica copies its primary (Redis calls it the master) over a replication link. While that link is down, or while the replica is still loading its first copy, its data may be out of date or empty. The replica-serve-stale-data setting decides what it does meanwhile:

yes, the default: it keeps answering, possibly with old data.
no: it refuses almost every command:

(error) MASTERDOWN Link with MASTER is down and replica-serve-stale-data is set to 'no'.

Only a short list of commands still work, such as INFO, ROLE, CONFIG, REPLICAOF, AUTH and SHUTDOWN (COMMAND INFO marks them with the stale flag). Reads and SCAN fail, and on Redis 8 and Valkey 8 so does PING, so a health check that pings the replica reports it down. Writes get READONLY as before, since a replica refuses writes anyway.

The replica keeps trying to reconnect, and answers normally as soon as the link is up and synced.

Common causes

The primary is down or unreachable: stopped, restarting, crashed, or cut off by the network or a firewall.
A first or full sync in progress. A new replica, or one that fell too far behind, copies the whole data set before the link counts as up. On a large data set that takes a while.
The replica can’t sign in to the primary. The primary has a password and the replica’s masterauth (and masteruser, with ACL users) is missing or wrong. The link never comes up.
A wrong primary address in replicaof, for example after the primary moved or was rebuilt.
A failover left this server replicating from a primary that no longer exists, or that isn’t a primary any more.

How to fix it

Find out why the link is down

On the replica:

redis-cli INFO replication

Look at master_host and master_port (the primary it’s trying to reach), master_link_status (down), master_sync_in_progress (1 during a sync) and master_link_down_since_seconds. The replica’s log says why each attempt failed. In the tests below, Redis logged MASTER aborted replication with an error: NOAUTH Authentication required. for a missing password, and Valkey Unable to connect to PRIMARY: Resource temporarily unavailable for a primary whose host name no longer resolved.

Fix what stops it

Primary down: start it again, or fix the network between them.
Password: set the primary’s password on the replica:
```
redis-cli CONFIG SET masterauth "<password>"
redis-cli CONFIG REWRITE
```
With ACL users, set masteruser too, to a user allowed to replicate.
Wrong address: REPLICAOF <primary-host> <primary-port>.

If the primary is gone for good, promote the replica

redis-cli REPLICAOF NO ONE

The replica becomes a primary with the data it has and answers again. Point your application, and any other replicas, at it. With Sentinel or a managed service, let it run the failover instead, so it doesn’t end up with two primaries.

Decide what the replica should do while it’s out of sync

replica-serve-stale-data no is the right choice when old data would do harm: readers get an error and can go to the primary. If reading slightly old data is fine (a cache, a dashboard), set it to yes:

redis-cli CONFIG SET replica-serve-stale-data yes

With no, a client that reads from replicas should be ready for this error and fall back to the primary when it comes.

Reproduce it

Two temporary Redis 8.10.2 containers on their own Docker network, the second a replica of the first, with stale data turned off:

docker network create seo-err-net
docker run --rm -d --name seo-err-primary --network seo-err-net redis:8 redis-server
docker run --rm -d --name seo-err-replica --network seo-err-net redis:8 redis-server --replicaof seo-err-primary 6379 --replica-serve-stale-data no

In its first seconds, before the first sync finished, the replica answered GET greeting with:

(error) MASTERDOWN Link with MASTER is down and replica-serve-stale-data is set to 'no'.

Five seconds later the replica’s log said MASTER <-> REPLICA sync: Finished with success, and GET greeting returned "hello", set on the primary with SET greeting hello. Then the primary was stopped (docker stop seo-err-primary). On the replica, GET, PING, DBSIZE, EXISTS, TYPE and SCAN 0 all got the MASTERDOWN error; SET x 1 got READONLY You can't write against a read only replica.; INFO replication and ROLE answered:

role:slave
master_host:seo-err-primary
master_port:6379
master_link_status:down
master_last_io_seconds_ago:-1
master_sync_in_progress:0

CONFIG SET replica-serve-stale-data yes
OK
GET greeting
"hello"
PING
PONG
CONFIG SET replica-serve-stale-data no
OK
REPLICAOF NO ONE
OK
GET greeting
"hello"
SET greeting bye
OK

A replica of a primary started with a password, without masterauth, never got its link up. Its log:

1:S 11 Oct 2026 10:54:53.422 # MASTER aborted replication with an error: NOAUTH Authentication required.
1:S 11 Oct 2026 10:54:53.423 * Reconnecting to MASTER seo-err-pwprimary:6379 after failure

GET on it got MASTERDOWN. After CONFIG SET masterauth <password> on the replica, master_link_status was up seven seconds later and GET replied (nil).

A temporary Valkey 8.1.10 primary and replica set up the same way gave the same message, word for word: for GET during the first sync, and for GET and PING after the primary was stopped.

In Inlet

Inlet connects to the server you give it, and doesn’t use Sentinel yet, so it won’t move to a new primary by itself: if a replica answers MASTERDOWN, connect to the primary instead. INFO replication and ROLE run in a query tab, with INFO shown as a table. The error links to this page.

MASTERDOWN Link with MASTER is down and replica-serve-stale-data is set to 'no'