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.
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.
Connect to the replica and inspect the full replication status:
redis-cli -h <replica-host> -p <replica-port>
> INFO replicationLook for "master_link_status:down" and read the "master_link_err" field for specific error messages like "Connection refused" or "Network unreachable".
Test connectivity from the replica to the master:
# 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> PINGIf 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.
Ensure the replica and master have matching password configuration:
# 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 masterauthIf they don't match, set the correct password on the replica:
redis-cli -h <replica-host> -p <replica-port> CONFIG SET masterauth <password>If the logs show "I/O error trying to sync with master: connection lost", the buffer is too small for the RDB transfer:
# 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 restartingThe format is: client-output-buffer-limit slave <hard-limit> <soft-limit> <soft-seconds>. Set high values if you have large datasets or slow replicas.
If network is now stable, force the replica to reconnect:
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:
redis-cli -h <replica-host> -p <replica-port> INFO replicationOnce "master_link_status:up" appears, replication is restored.
If using Sentinel, verify Sentinel itself is working:
# 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 mymasterEnsure 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.
To prevent MASTERDOWN errors from blocking all requests, decide on your consistency requirements:
# 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 yesSetting 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.
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).
ERR fsync error
How to fix "ERR fsync error" in Redis
CLUSTERDOWN The cluster is down
How to fix 'CLUSTERDOWN The cluster is down' in Redis
ERR Job for redis-server.service failed because a timeout was exceeded
Job for redis-server.service failed because a timeout was exceeded
ERR Unbalanced XREAD list of streams
How to fix "ERR Unbalanced XREAD list" in Redis
ERR syntax error
How to fix "ERR syntax error" in Redis