Redis Replication Setup: Master-Replica Configuration and Troubleshooting

Quick Answer

• What it does: Redis replication creates real-time copies of a master dataset on one or more replica nodes, enabling read scaling, data redundancy, and failover capability.
• First checks: Verify the master is reachable from the replica, confirm authentication credentials match, and ensure the replica's replicaof directive points to the correct master host and port.
• Minimal setup: Start a replica with redis-server --port 6380 --replicaof localhost 6379 or add replicaof localhost 6379 to redis.conf.
• Key boundary: Redis replication is asynchronous by default—data loss is possible on master failure. Use WAIT for synchronous acknowledgment or accept the trade-off.
• Version note: Applies to Redis 5.0+ where replicaof replaces the legacy slaveof command (still accepted for backward compatibility).

What Problem It Solves

Redis replication addresses three production concerns:

1. High availability: If the master fails, a replica can be promoted to master, minimizing downtime.
2. Read scaling: Replicas serve read traffic, offloading the master for write-heavy workloads.
3. Data redundancy: Replicas maintain independent copies of the dataset, protecting against data loss from disk failures or accidental deletion.

For AI applications using MCP hosts like Claude Desktop or Cursor, Redis replication provides a low-latency state store that can serve as memory, cache, or session storage with failover capability.

Installation and Quick Start

Redis replication requires no additional packages—it's built into the core server. Install Redis on each node:

BASH
# Debian/Ubuntu
apt-get install redis-server

# RHEL/CentOS
yum install redis

# macOS (Homebrew)
brew install redis

Start a master on the default port:

BASH
redis-server --port 6379

Start a replica on port 6380:

BASH
redis-server --port 6380 --replicaof localhost 6379

Verify replication status:

BASH
redis-cli -p 6380 INFO replication

Look for role:slave (or role:replica in Redis 7+) and master_link_status:up.

Minimal Working Configuration

For a production-ready replica, create a dedicated configuration file:

CONF
# /etc/redis/replica.conf
port 6380
replicaof localhost 6379

# Authentication (if master requires a password)
masterauth your-master-password

# Persistence on replica
dir /var/lib/redis-replica
dbfilename dump.rdb
appendonly yes
appendfilename "appendonly.aof"

# Replication tuning
repl-backlog-size 64mb
repl-timeout 60

Start with the config file:

BASH
redis-server /etc/redis/replica.conf

For MCP host integration, the equivalent JSON configuration:

JSON
{
  "mcpServers": {
    "redis-replica": {
      "command": "redis-server",
      "args": [
        "--port", "6380",
        "--replicaof", "localhost", "6379",
        "--dir", "/data",
        "--dbfilename", "dump.rdb"
      ]
    }
  }
}

Parameters and Environment Variables

Key configuration directives for replication:

Root Cause Analysis

Redis replication operates in two phases:

1. Full resync: The replica sends PSYNC to the master. The master forks a child process, creates an RDB snapshot, and streams it to the replica. The replica loads the snapshot, then applies buffered commands.
2. Incremental propagation: After the initial sync, the master streams every write command to the replica in real time.

The critical failure modes:

• Asynchronous loss: The master acknowledges writes to clients before replicas confirm receipt. A master crash between acknowledgment and replication means those writes are lost.
• Backlog overflow: If a replica disconnects longer than the backlog buffer can hold, a full resync is required. A large repl-backlog-size reduces this risk.
• Persistence trap: If the master has persistence disabled and restarts, it starts empty. Replicas then sync from the empty master, wiping their data. Always disable auto-restart for masters without persistence.

Common Errors and Fixes

Production Notes and Security Checks

Security hardening:

• Enable requirepass on the master and mirror it with masterauth on replicas.
• Use TLS for replication traffic: configure tls-replication yes and provide certificates.
• Restrict network access with firewall rules—only allow replica nodes to reach the master's port.
• Run replicas on separate hosts or availability zones for true redundancy.

Operational safeguards:

• If the master has persistence disabled, disable its auto-restart (systemctl disable redis-server or equivalent). Otherwise, a restart creates an empty master that propagates emptiness to replicas.
• Monitor replication health with INFO replication—watch master_link_status, master_repl_offset, and slave_repl_offset. Offsets should converge.
• Set up alerting for master_link_status:down and for replica lag exceeding acceptable thresholds.
• Test failover procedures regularly: promote a replica, verify writes, then rebuild the failed node as a new replica.

Data consistency caveats:

• Redis replication is eventually consistent, not strongly consistent.
• Use WAIT numreplicas timeout after critical writes to block until replicas acknowledge, reducing (but not eliminating) loss risk.
• For strict consistency requirements, consider Redis Cluster with WAIT or an external consensus system.

FAQ

Q: Does Redis replication guarantee strong data consistency?

A: No. Redis uses asynchronous replication by default—the master doesn't wait for replica acknowledgment before confirming writes to clients. A master failure can lose recent writes. The WAIT command forces synchronous acknowledgment for specific writes, but it only reduces the loss window; it doesn't provide strong consistency guarantees.

Q: How do I avoid data loss when the master has persistence disabled?

A: Disable automatic restart for the master. If a master without persistence restarts, it loads an empty dataset, and replicas will sync from it, wiping their data. Ensure at least one replica has persistence enabled (appendonly yes or RDB snapshots), and promote a replica before restarting a failed master.

Q: How do I monitor replication health?

A: Run redis-cli INFO replication on both master and replicas. Key fields: master_link_status (up/down), master_repl_offset and slave_repl_offset (should match or converge), master_last_io_seconds_ago (time since last communication). Set up monitoring alerts for link-down events and offset divergence.

Official References

• Redis Replication Documentation