How to fix MASTERDOWN Link with MASTER is down in Redis

RedisINTERMEDIATEHIGHUpdated Dec 29, 2025· 206 views

The MASTERDOWN error occurs when a Redis replica loses its connection to the master and replica-serve-stale-data is disabled. This error is common in Redis Sentinel deployments and indicates a replication link failure that prevents the replica from serving requests.

Quick fix

Fixes MASTERDOWN Link with MASTER is down

redis-cli -h <replica-host> -p <replica-port>
> INFO replication
  1. Check replication status and error details
  2. Verify master is running and reachable
  3. Verify authentication credentials match
  4. Increase client output buffer limits if needed
redis — error
redis-cli -h <replica-host> -p <replica-port>
> INFO replication
MASTERDOWN Link with MASTER is down

What this error means

The MASTERDOWN error is returned by a Redis replica when it loses connection to its master and replica-serve-stale-data is set to "no". In Redis, when a replica cannot connect to the master, it has two modes: if replica-serve-stale-data is "yes" (default), it continues serving potentially outdated data; if "no", it replies with an error to client commands. This error is also used as a valid PING response in Redis Sentinel deployments to indicate that a replica knows its master is unreachable. MASTERDOWN is not a failure state by itself—it's a protective mechanism that prevents clients from reading inconsistent data when replication is broken.

Typical symptoms

  • Replica responds with MASTERDOWN error to client commands
  • Replication sync failures in logs with "Link with MASTER is down"
  • Replica shows "master_link_status:down" in INFO replication output
  • Clients cannot write to replica (expected behavior) when read-only mode is enabled
  • Sentinel may detect SDOWN (Subjectively Down) state if MASTERDOWN persists

Common causes

  1. Network connectivity issues between replica and master (latency, packet loss, firewall blocks)
  2. Master process is down, restarting, or unreachable
  3. Client output buffer limits too small, causing disconnection during RDB sync
  4. Master is performing a long operation (snapshot, persistence) that delays responses
  5. Replica-serve-stale-data is explicitly set to "no" in redis.conf
  6. Authentication failure due to mismatched passwords or missing requirepass
  7. Port mismatch between master advertised port and replica connection port

How to fix "MASTERDOWN Link with MASTER is down"

1Check replication status and error details

Connect to the replica and inspect the full replication status:

bash
redis-cli -h <replica-host> -p <replica-port>
> INFO replication

Look for "master_link_status:down" and read the "master_link_err" field for specific error messages like "Connection refused" or "Network unreachable".

2Verify master is running and reachable

Test connectivity from the replica to the master:

bash
# From replica host, test TCP connection
telnet <master-host> <master-port>

# Or use redis-cli to ping the master directly
redis-cli -h <master-host> -p <master-port> PING

If you see "PONG", the master is running and reachable. If you see "connection refused" or timeout, the master process is down or the port is incorrect.

3Verify authentication credentials match

Ensure the replica and master have matching password configuration:

bash
# Check master's requirepass (if set)
redis-cli -h <master-host> -p <master-port> CONFIG GET requirepass

# Check replica's masterauth (must match master's requirepass)
redis-cli -h <replica-host> -p <replica-port> CONFIG GET masterauth

If they don't match, set the correct password on the replica:

bash
redis-cli -h <replica-host> -p <replica-port> CONFIG SET masterauth <password>
4Increase client output buffer limits if needed

If the logs show "I/O error trying to sync with master: connection lost", the buffer is too small for the RDB transfer:

bash
# Check current limit
redis-cli -h <master-host> -p <master-port> CONFIG GET client-output-buffer-limit

# Increase the slave buffer (dynamically)
redis-cli -h <master-host> -p <master-port> CONFIG SET client-output-buffer-limit "slave 1024mb 256MB 0"

# Persist by editing redis.conf and restarting

The format is: client-output-buffer-limit slave <hard-limit> <soft-limit> <soft-seconds>. Set high values if you have large datasets or slow replicas.

5Manually reconnect replica to master

If network is now stable, force the replica to reconnect:

bash
redis-cli -h <replica-host> -p <replica-port> REPLICAOF <master-host> <master-port>

# For Redis < 5.0, use SLAVEOF instead
redis-cli -h <replica-host> -p <replica-port> SLAVEOF <master-host> <master-port>

Monitor the connection with:

bash
redis-cli -h <replica-host> -p <replica-port> INFO replication

Once "master_link_status:up" appears, replication is restored.

6For Sentinel deployments: check quorum and configuration

If using Sentinel, verify Sentinel itself is working:

bash
# Check master status via Sentinel
redis-cli -h <sentinel-host> -p <sentinel-port> SENTINEL masters
redis-cli -h <sentinel-host> -p <sentinel-port> SENTINEL slaves mymaster

# Verify Sentinel can see the master
redis-cli -h <sentinel-host> -p <sentinel-port> SENTINEL get-master-addr-by-name mymaster

Ensure at least a quorum of Sentinel nodes agree the master is reachable. If Sentinel fails to promote a replica after master failure, check hostname resolution and network connectivity between Sentinel and all Redis instances.

7Configure replica-serve-stale-data appropriately

To prevent MASTERDOWN errors from blocking all requests, decide on your consistency requirements:

bash
# Allow serving stale data (default, more availability)
redis-cli -h <replica-host> -p <replica-port> CONFIG SET replica-serve-stale-data yes

# Persist to redis.conf
replica-serve-stale-data yes

Setting to "yes" means clients get potentially outdated data during outages, but requests don't fail with MASTERDOWN. Set to "no" only if you require strict consistency and can tolerate request failures during master outages.

Advanced notes

MASTERDOWN vs SDOWN: In Redis Sentinel, -MASTERDOWN is a valid PING response indicating a replica knows its master is unreachable. This is different from SDOWN (Subjectively Down), where one Sentinel believes a master is down. SDOWN is promoted to ODOWN (Objectively Down) when a quorum of Sentinels agree, triggering failover. Failover requires at least the configured quorum number of Sentinels to be reachable; if quorum is lost, failover cannot proceed. In Kubernetes deployments (e.g., Bitnami Helm charts), MASTERDOWN during readiness probes can block traffic to replicas even if replication will eventually recover; configure replica-serve-stale-data=yes and increase probe grace periods for stability. Connection buffer tuning is critical for large datasets; undersized buffers cause connection drops during RDB sync. Monitor "master_link_err" in INFO replication for diagnostic messages; common patterns include "Connection refused" (master down), "No route to host" (network/firewall), "Authentication failed" (password mismatch), and "Connection timeout" (master overloaded or slow network).

Frequently asked questions

What does "MASTERDOWN Link with MASTER is down" mean?
The MASTERDOWN error is returned by a Redis replica when it loses connection to its master and replica-serve-stale-data is set to "no". In Redis, when a replica cannot connect to the master, it has two modes: if replica-serve-stale-data is "yes" (default), it continues serving potentially outdated data; if "no", it replies with an error to client commands. This error is also used as a valid PING response in Redis Sentinel deployments to indicate that a replica knows its master is unreachable.
How do I fix "MASTERDOWN Link with MASTER is down"?
The MASTERDOWN error occurs when a Redis replica loses its connection to the master and replica-serve-stale-data is disabled. This error is common in Redis Sentinel deployments and indicates a replication link failure that prevents the replica from serving requests.
What causes "MASTERDOWN Link with MASTER is down"?
Network connectivity issues between replica and master (latency, packet loss, firewall blocks) Master process is down, restarting, or unreachable Client output buffer limits too small, causing disconnection during RDB sync
Is the "MASTERDOWN Link with MASTER is down" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading