Redis "MOVED" Error: What It Means in Redis Cluster and How to Fix It
The Redis MOVED error means you hit a cluster node that doesn't own the key's hash slot. How cluster mode works, cluster-aware clients, CROSSSLOT and ASK.
A Redis MOVED error means you're talking to a Redis Cluster (or a Valkey cluster), and the node you asked doesn't hold the key. The reply tells you which node does. Cluster-aware clients follow that redirect automatically, so seeing MOVED as an error means your client isn't in cluster mode: redis-cli without -c, a plain client pointed at one cluster node, or a managed service with cluster mode enabled that you're connecting to like a single server. The fix is to switch the client to cluster mode, not to change the data.
Checked against the Redis Cluster specification on redis.io, the Redis and Valkey server source, the node-redis, ioredis and redis-py docs, and AWS ElastiCache's endpoint docs in November 2026.
Here's the error from redis-cli:
127.0.0.1:7000> SET foo bar
(error) MOVED 12182 127.0.0.1:7002
The cluster specification uses -MOVED 3999 127.0.0.1:6381 as its example. Either way, the format is the same: MOVED <hash slot> <host>:<port>. Application libraries wrap it in their own error types, but the message still starts with MOVED.
How Redis Cluster decides where a key lives
A Redis Cluster splits the keyspace across several primary nodes using 16,384 hash slots. Every key maps to exactly one slot:
HASH_SLOT = CRC16(key) mod 16384
Each primary owns a range of slots. With three primaries, one might own slots 0-5460, the next 5461-10922, and the last 10923-16383. You can ask any node which slot a key belongs to:
127.0.0.1:7000> CLUSTER KEYSLOT foo
(integer) 12182
When you send a command to a node that doesn't own the key's slot, it doesn't forward the request. It replies with MOVED and the address of the node that does. The spec describes the expected client behaviour: reissue the command to that node, remember that the slot lives there, and ideally refresh the whole slot map (with CLUSTER SHARDS, or the older CLUSTER SLOTS), since "it is likely multiple slots were reconfigured rather than just one".
So MOVED is a normal part of the protocol. A cluster-aware client handles it silently and, once its slot map is current, sends each command to the right node first time.
Step 1: confirm you're on a cluster
redis-cli -h your-host -p 6379 INFO cluster
cluster_enabled:1 means this node is part of a cluster, and every client that talks to it must be cluster-aware. cluster_enabled:0 means it's a standalone server, and you shouldn't be seeing MOVED at all from it. Check you're connecting to the host you think you are.
Step 2: make the client cluster-aware
redis-cli
Add -c:
$ redis-cli -c -p 7000
127.0.0.1:7000> SET foo bar
-> Redirected to slot [12182] located at 127.0.0.1:7002
OK
127.0.0.1:7002>
The prompt changes because redis-cli has reconnected to the node that owns the slot. The same flag works with valkey-cli.
Node.js with node-redis
Use createCluster instead of createClient. You list a few nodes and the client discovers the rest:
import { createCluster } from 'redis';
const cluster = createCluster({
rootNodes: [
{ url: 'redis://10.0.0.1:30001' },
{ url: 'redis://10.0.0.2:30002' },
],
});
cluster.on('error', (err) => console.error('Redis Cluster Error', err));
await cluster.connect();
await cluster.set('foo', 'bar');
Per the node-redis clustering docs, it follows MOVED and ASK up to maxCommandRedirections times (default 16). Username and password go under defaults.
Node.js with ioredis
import Redis from 'ioredis';
const cluster = new Redis.Cluster([
{ host: '127.0.0.1', port: 7000 },
{ host: '127.0.0.1', port: 7001 },
]);
The ioredis README says you only need "a few" nodes in the list; it finds the others after connecting. Redirections are capped by maxRedirections (default 16).
Python with redis-py
from redis.cluster import RedisCluster
rc = RedisCluster(host="localhost", port=7000)
rc.set("foo", "bar")
A plain redis.Redis(...) client pointed at a cluster node will raise the MOVED error instead of following it. redis-py's cluster docs also show RedisCluster.from_url(...) and a startup_nodes list.
Libraries built on top of these clients (session stores, rate limiters, job queues) usually have their own setting for cluster mode. Check their docs before you assume they pass it through.
Step 3: on a managed service, use the right endpoint
Managed Redis and Valkey often offer a "cluster mode" switch, and the endpoint you connect to changes with it. On AWS ElastiCache, the endpoint docs say:
| ElastiCache mode | Connect to | Client |
|---|---|---|
| Cluster mode disabled | Primary endpoint (writes), reader endpoint (reads) | Any client |
| Cluster mode enabled | The cluster's configuration endpoint | Must support Valkey Cluster or Redis OSS Cluster |
The classic way to hit MOVED is a cluster-mode-enabled cache with a non-cluster client, or a client pointed at one node's endpoint. The data is spread across shards, so any key outside that node's slots comes back as MOVED. Point a cluster-aware client at the configuration endpoint.
Related errors you'll meet next
CROSSSLOT
Once you're in cluster mode, commands that touch several keys only work if all the keys are in the same slot:
127.0.0.1:7000> MSET user:1000 a cart:1000 b
(error) CROSSSLOT Keys in request don't hash to the same slot
This applies to MSET, MGET, SUNION, multi-key Lua scripts and MULTI/EXEC transactions. The fix is a hash tag: if a key contains {...}, only the part inside the first pair of braces is hashed. {user:1000}:profile and {user:1000}:cart always land in the same slot, so this works:
MSET {user:1000}:profile a {user:1000}:cart b
Use tags that group keys you need together (one user, one order), not one tag for everything. A single tag puts all your data in one slot on one node and defeats the point of the cluster.
Job queues are the common case. BullMQ's Redis Cluster docs say its internals need atomic operations across several keys, and ask you to put the queue prefix in braces (prefix: '{myprefix}'). (BullMQ tutorial)
If you need a multi-key read across slots and don't need it to be atomic, redis-py offers mget_nonatomic and mset_nonatomic, which split the keys by slot and send one batch per node.
ASK
ASK looks like MOVED but means something narrower. While a slot is being migrated between nodes, a key may already have moved to the new node:
| MOVED | ASK | |
|---|---|---|
| Meaning | This slot now lives on another node | This one key has already moved; the slot hasn't finished migrating |
| Client should | Retry there and update its slot map | Send ASKING, then retry that one command there; don't update the map |
| When you see it | Topology changes, wrong client mode | Only during resharding |
Cluster-aware clients handle both. You'll only see ASK as an error with a client that isn't cluster-aware, or one that's missing proper ASK support.
During resharding you may also get TRYAGAIN for multi-key commands whose keys are split between source and destination. The spec says to retry after a short wait.
Step 4: still getting MOVED with a cluster client?
- The redirect points at an address you can't reach. Nodes announce their own addresses. In Docker or behind NAT, those can be internal IPs your app can't route to, so the client follows
MOVEDto a dead end. Map them in the client (natMapin ioredis,nodeAddressMapin node-redis) or setcluster-announce-ipon the nodes. - Reads from replicas. Replicas redirect reads to their primary unless the connection sent
READONLY. Use the client's replica option (useReplicasin node-redis,read_from_replicas=Truein redis-py) rather than connecting to a replica by hand. - Pipelines in ioredis. ioredis sends a whole pipeline to one node, so all the keys in it must belong to slots on that node. Use hash tags for keys you pipeline together.
- Endless redirects. Hitting the redirect limit usually means the cluster itself is unhealthy, for example mid-failover or with uncovered slots. Run
CLUSTER INFOand checkcluster_state:ok.
Do you need a cluster at all?
Cluster mode exists to spread data and load across several machines. Many apps that get MOVED turned it on by default in a managed console and don't need it: one primary with a replica handles a lot of caching, sessions and queue traffic. If you're starting out, cluster mode disabled keeps every client simple. See when a small app actually needs Redis and Redis vs Valkey if you're also choosing an engine.
EasySpawn provisions Redis on the same server as your app and hands your code the connection details as REDIS_URL, so connecting is one environment variable rather than a choice of endpoints and modes. If you later outgrow it and move to a cluster, the client changes above are the ones you'd make. See how it works or join the waitlist.
Related: Redis vs Valkey: Licences, Compatibility and Which to Pick in 2026 · Redis: When a Small App Actually Needs It (and When Postgres Is Enough) · BullMQ Tutorial: Background Jobs in Node.js With Redis · Horizontal vs Vertical Scaling: How Apps Handle More Users
Keep reading
pg_stat_statements: Find the Queries Slowing Down Your Postgres
pg_stat_statements records statistics for every distinct query your database runs — calls, total and mean time, rows, cache hits. How to enable it, the queries to find what costs the most, interpreting the results, resetting, and turning findings into indexes and fixes.
The N+1 Query Problem: How to Spot It and Fix It
The most common performance bug in ORM-based apps: one query for a list, then one more per item. How N+1 happens in Prisma, Drizzle, Django, Rails, and GraphQL resolvers, how to detect it from logs and pg_stat_statements, and the fixes — eager loading, batching, joins, and DataLoader.