🚨 Redis Error Guide: 'MASTERDOWN Link with MASTER is down and replica-serve-stale-data is no'

Overview

MASTERDOWN Link with MASTER is down and replica-serve-stale-data is set to 'no' is returned by a replica when its connection to the master is broken and it has been configured to refuse serving potentially stale data. By default replica-serve-stale-data yes, so a replica keeps answering reads with whatever data it has even while disconnected. Set it to no and the replica instead rejects reads with MASTERDOWN until it re-establishes the link and resynchronizes — a deliberate consistency-over-availability choice.

The literal error a client reads from the replica:

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

So this error is really two facts at once: (1) the replica cannot reach its master (master_link_status:down), and (2) you have opted out of stale reads. Fixing it means restoring replication — the config is working as intended.

Symptoms

• Reads against a replica fail with MASTERDOWN while the master (if up) still serves fine.
• INFO replication on the replica shows master_link_status:down.
• The replica log shows repeated connection/auth/resync failures to the master.
• Under Sentinel/Cluster, a failover is in progress or a replica is orphaned.

redis-cli -p 6380 INFO replication | grep -E 'role|master_link_status|master_last_io'

role:slave
master_link_status:down
master_last_io_seconds_ago:143

Common Root Causes

1. Master is actually down

Crash, OOM-kill, or restart. Every replica loses its link.

redis-cli -h <master> -p 6379 PING
sudo systemctl status redis --no-pager
journalctl -u redis --no-pager | tail -20

2. Network partition / firewall between replica and master

The master is up but unreachable from the replica (routing, security group, port 6379 blocked).

nc -vz <master-ip> 6379

Connection to <master-ip> 6379 port [tcp/*] failed: Connection timed out

3. Authentication failure (masterauth mismatch)

After a password rotation, the replica cannot authenticate and the link stays down.

# replica redis.conf
replicaof <master-ip> 6379
masterauth <MASTER_PASSWORD>
replica-serve-stale-data no

MASTER aborted replication with an error: NOAUTH Authentication required.

4. Resync failing (disk, backlog, timeout)

The replica connects but full resync fails — out of disk for the RDB, repl-backlog-size too small for partial resync, or repl-timeout too short over a slow link.

redis-cli -p 6380 INFO replication | grep -E 'master_sync_in_progress|master_link'
redis-cli -p 6380 CONFIG GET repl-timeout
redis-cli -h <master> CONFIG GET repl-backlog-size

Diagnostic Workflow

Step 1: Confirm the link state on the replica

redis-cli -p 6380 INFO replication

role:slave
master_host:10.0.0.5
master_port:6379
master_link_status:down
master_last_io_seconds_ago:143
master_sync_in_progress:0

master_link_status:down confirms the replica is disconnected; master_last_io_seconds_ago tells you how long.

Step 2: Check the master is alive and reachable

redis-cli -h 10.0.0.5 -p 6379 PING
nc -vz 10.0.0.5 6379

PONG + open port = master fine, look at auth/resync. Timeout = network. No process = master down.

Step 3: Read the replica log for the exact failure

journalctl -u redis --no-pager | grep -iE 'MASTER|sync|auth|link' | tail -20

Connecting to MASTER 10.0.0.5:6379
MASTER <-> REPLICA sync started
MASTER aborted replication with an error: NOAUTH Authentication required.

NOAUTH/WRONGPASS → masterauth; timed out → network; Can't save ... No space left → disk.

Step 4: Verify auth and resync capacity

redis-cli -p 6380 CONFIG GET masterauth
redis-cli -h 10.0.0.5 CONFIG GET requirepass
df -h $(redis-cli -p 6380 CONFIG GET dir | tail -1)
redis-cli -h 10.0.0.5 INFO replication | grep -E 'connected_slaves|repl_backlog'

Example Root Cause Analysis

Overnight, a read replica behind the API started returning MASTERDOWN. The service had replica-serve-stale-data no for consistency, so disconnection meant hard read failures.

redis-cli -p 6380 INFO replication | grep master_link_status

master_link_status:down

The master answered PING and port 6379 was open, so it was not down and not a network cut. The replica log showed the cause:

MASTER aborted replication with an error: WRONGPASS invalid username-password pair

A requirepass rotation on the master had updated the master’s config and clients, but the replica’s masterauth was left stale. Fix: update masterauth on the replica and reload replication.

redis-cli -p 6380 CONFIG SET masterauth '<NEW_PASSWORD>'   # then persist to redis.conf
redis-cli -p 6380 REPLICAOF 10.0.0.5 6379                  # re-trigger the link
redis-cli -p 6380 INFO replication | grep master_link_status

master_link_status:up

The link came up, a partial resync completed, and reads recovered. Long term, masterauth/requirepass were moved into config management so rotations update master and replicas atomically.

Prevention Best Practices

• Manage requirepass and masterauth together in config management so password rotations never desync master and replicas.
• Decide replica-serve-stale-data deliberately: no favors consistency (fails fast), yes favors availability (stale reads). Match it to the app.
• Size repl-backlog-size generously so brief blips heal via partial resync instead of a full resync.
• Ensure the replica’s dir has enough free disk for a full RDB, and raise repl-timeout on slow/high-latency links.
• Run Sentinel or Cluster so a genuinely dead master triggers automatic failover instead of prolonged MASTERDOWN.
• Alert on master_link_status:down and rising master_last_io_seconds_ago; see more Redis error guides.

Quick Command Reference

# Replica link state
redis-cli -p 6380 INFO replication | grep -E 'role|master_link_status|master_last_io|sync_in_progress'

# Is the master alive & reachable?
redis-cli -h <master> -p 6379 PING
nc -vz <master> 6379

# Exact failure in the replica log
journalctl -u redis | grep -iE 'MASTER|sync|auth|link' | tail -20

# Auth, disk, backlog
redis-cli -p 6380 CONFIG GET masterauth
df -h $(redis-cli -p 6380 CONFIG GET dir | tail -1)
redis-cli -h <master> INFO replication | grep repl_backlog

# Re-establish replication
redis-cli -p 6380 REPLICAOF <master> 6379

Conclusion

MASTERDOWN Link with MASTER is down and replica-serve-stale-data is set to 'no' is a replica refusing reads because it lost its master link and you configured it to fail rather than serve stale data. It is two conditions combined — a broken link plus a strict consistency setting. To resolve it, restore replication:

1. Master down/OOM — recover or fail over the master.
2. Network/firewall cutting port 6379 — restore connectivity.
3. masterauth/requirepass mismatch after a rotation — realign the passwords.
4. Resync failing on disk, backlog, or timeout — free disk, grow repl-backlog-size, raise repl-timeout.

INFO replication (master_link_status, master_last_io_seconds_ago) plus the replica log’s exact message tell you which one you are chasing.