🚨 Redis Error Guide: 'MOVED <slot> <host:port>' — Use a Cluster-Aware Client

Overview

MOVED <slot> <host:port> is a Redis Cluster redirection. Every key maps to one of 16384 hash slots, and each slot is owned by exactly one master. When you send a command for a key to a node that does not own that key’s slot, the node replies with MOVED, telling you which node does own it. A cluster-aware client is expected to follow the redirect (and update its slot map); a non-cluster client just sees an error.

The literal error clients receive:

(error) MOVED 8404 10.0.0.32:6379

MOVED is not a failure — it is the cluster protocol working as designed. The “problem” is almost always a client that is not cluster-aware (or redis-cli run without -c), or a client with a stale slot map after a reshard/failover. Understanding MOVED (permanent redirect) versus ASK (temporary, during slot migration) tells you whether the ownership changed for good or just for the moment.

Symptoms

• Commands return MOVED <slot> <host:port> instead of a result.
• redis-cli without -c shows the redirect; with -c it follows automatically.
• Appears or increases after resharding, adding/removing nodes, or a failover.

redis-cli -h 10.0.0.30 GET user:1

(error) MOVED 8404 10.0.0.32:6379

redis-cli -c -h 10.0.0.30 GET user:1

-> Redirected to slot [8404] located at 10.0.0.32:6379
"alice"

Common Root Causes

1. Non-cluster-aware client (or redis-cli without -c)

The client treats the cluster like a single node and does not follow redirects.

redis-cli -h <NODE> GET <key>          # shows MOVED
redis-cli -c -h <NODE> GET <key>       # follows it

The difference between these two commands is the whole diagnosis.

2. Stale slot map after resharding

The client cached the slot→node map; a reshard moved slots, so the cached target now redirects.

redis-cli CLUSTER SLOTS
redis-cli CLUSTER NODES | awk '{print $2, $9}'

10.0.0.32:6379 0-5460
10.0.0.31:6379 5461-10922

3. Failover changed the slot owner

A replica was promoted; the slot’s owning node address changed and clients with a stale map redirect.

redis-cli CLUSTER NODES | grep master
redis-cli INFO replication | grep -E 'role'

4. Connecting to a replica for writes/most reads

Replicas own no slots for serving by default; they redirect reads (unless READONLY) and all writes to the slot master.

redis-cli -h <REPLICA> GET <key>       # MOVED to the master

Diagnostic Workflow

Step 1: Confirm cluster mode and health

redis-cli CLUSTER INFO | grep -E 'cluster_enabled|cluster_state|cluster_slots_assigned'

cluster_state:ok
cluster_slots_assigned:16384

cluster_state:ok with all 16384 slots assigned means the cluster is healthy and MOVED is normal routing.

Step 2: Find which node owns the slot

redis-cli CLUSTER KEYSLOT <key>
redis-cli CLUSTER SLOTS
redis-cli CLUSTER NODES | awk '{print $2, $9}'

Match the key’s slot to the owning node.

Step 3: Reproduce with and without cluster mode

redis-cli -h <NODE> GET <key>          # MOVED
redis-cli -c -h <NODE> GET <key>       # follows -> value

If -c works, the client simply is not cluster-aware.

Step 4: Check for a recent reshard or failover

sudo journalctl -u redis-server --no-pager | grep -iE 'Cluster|slot|FAILOVER|reconfig' | tail
redis-cli CLUSTER NODES | grep -E 'fail|handshake|migrating|importing'

Step 5: Verify slot coverage is complete

redis-cli --cluster check <NODE>:6379

Example Root Cause Analysis

At 12:05, after scaling a Redis Cluster from 3 to 4 masters and resharding, a batch job starts logging MOVED 8404 10.0.0.32:6379 on many reads. The job uses a plain (non-cluster) Redis client pointed at a single seed node.

CLUSTER INFO shows the cluster itself is healthy — cluster_state:ok, all 16384 slots assigned — so this is routing, not an outage:

redis-cli CLUSTER INFO | grep -E 'cluster_state|cluster_slots_assigned'
# cluster_state:ok / cluster_slots_assigned:16384

The reshard moved slot 8404 to the new node 10.0.0.32, but the job’s client does not follow MOVED and cannot rebuild its slot map. Confirming with redis-cli:

redis-cli -h 10.0.0.30 GET user:1        # (error) MOVED 8404 10.0.0.32:6379
redis-cli -c -h 10.0.0.30 GET user:1     # -> Redirected ... "alice"

The root cause is the non-cluster client. The fix is to switch the job to a cluster-aware client configured with multiple seed nodes so it discovers and refreshes the slot map:

# Cluster client config (pseudocode)
RedisCluster(startup_nodes=[10.0.0.30:6379, 10.0.0.31:6379, 10.0.0.32:6379])
# The client follows MOVED and refreshes its slot map on redirect

After the switch, MOVED redirects are handled transparently and the job completes. The client also now refreshes its topology on MOVED, so future reshards and failovers are absorbed automatically.

Prevention Best Practices

• Always use a cluster-aware client for Redis Cluster; configure it with several seed nodes so it can bootstrap and refresh the slot map.
• Ensure the client refreshes its topology on MOVED (and handles ASK during migrations) rather than caching a slot map forever.
• Understand MOVED (permanent ownership change — update your map) vs ASK (temporary during a live slot migration — one-shot redirect, do not update the map).
• Expect a burst of MOVED right after resharding or failover; it should subside as clients refresh — alert only if it persists.
• Verify slot coverage with redis-cli --cluster check after any topology change.
• For interactive debugging, always add -c to redis-cli so it follows redirects like a real client.
• Paste the redirect and CLUSTER NODES output into the free incident assistant, and see more Redis guides.

Quick Command Reference

# Cluster health and slot assignment
redis-cli CLUSTER INFO | grep -E 'cluster_state|cluster_slots_assigned'

# Which node owns the key's slot?
redis-cli CLUSTER KEYSLOT <key>
redis-cli CLUSTER SLOTS
redis-cli CLUSTER NODES | awk '{print $2,$9}'

# Reproduce: without vs with cluster mode
redis-cli -h <NODE> GET <key>
redis-cli -c -h <NODE> GET <key>

# Reshard / failover history & coverage
sudo journalctl -u redis-server | grep -iE 'slot|FAILOVER|Cluster' | tail
redis-cli --cluster check <NODE>:6379

Conclusion

MOVED <slot> <host:port> is Redis Cluster telling you which node owns a key’s slot — it is normal routing, not an outage. The typical situations are:

1. A non-cluster-aware client (or redis-cli without -c) that does not follow redirects.
2. A stale slot map after resharding.
3. A failover that changed the slot’s owning node.
4. Hitting a replica for a command the master must serve.

The fix is a cluster-aware client seeded with multiple nodes that follows MOVED and refreshes its topology. Confirm the cluster is healthy with CLUSTER INFO, map the slot with CLUSTER SLOTS, and remember MOVED (permanent) versus ASK (temporary migration) so you know whether ownership changed for good.