Context
Redis Cluster assigns keys to hash slots and distributes those slots across nodes. A cluster-aware client uses that mapping to route commands. Some errors are directions for the client, while others reveal an incompatible multi-key operation. Identify which condition you have before changing the cluster or adding retries.
Prerequisites
Collect Redis and client-library versions, connection mode, seed endpoints, advertised node addresses, recent resharding or failover events, and a sanitized failing command shape. Key names can contain business identifiers, so use protected diagnostics. Obtain read access to cluster topology. Reproduce errors with synthetic keys in staging rather than running a migration or multi-key write against production as a test.
Follow the routing decision
- Confirm that the application uses the library's Redis Cluster mode. A standalone client may successfully connect to a seed node yet expose redirections directly to the application. Inspect current topology using supported read-only commands such as
CLUSTER SHARDSon versions that provide it. Confirm that every advertised destination is reachable from the application network. - Classify redirections correctly.
MOVEDpoints toward a slot's owner and normally leads the client to refresh its mapping.ASKis a temporary direction associated with migration and has different per-command handling. A library that treats them identically can behave incorrectly during resharding even when ordinary steady-state queries work. - For
CROSSSLOT, inspect the complete key set used by the command or script. Commands needing several keys generally require compatible slot placement. Use read-onlyCLUSTER KEYSLOTchecks with synthetic names to test the naming design. Hash tags can place related keys together, but placing an entire application's keys under one tag can concentrate demand on one slot. - Test the correction with representative cluster events. Upgrade or configure the client if redirection support is missing, repair advertised endpoints if destinations are unreachable, or redesign multi-key boundaries when placement is incompatible. Do not manually move slots or force cluster-state changes merely to suppress an application routing error.
Diagnostic table
| Error or symptom | Meaning to investigate | Useful correction |
|---|---|---|
| MOVED reaches application code | Client routing is incomplete | Enable supported cluster handling |
| ASK fails only during migration | Temporary redirect path broken | Verify library migration behavior |
| CROSSSLOT repeats unchanged | Keys do not share required placement | Review key and operation design |
| Redirect points to unreachable address | Advertised route differs from client path | Fix node reachability or advertisement |
Illustrative scenario
An application performs a multi-key inventory update using keys with unrelated names. It works against a standalone development server but fails with CROSSSLOT in the cluster. The team models a bounded inventory unit and tests a shared hash tag for keys that truly need one atomic operation. It separately evaluates distribution so the fix does not place all inventory traffic in one slot.
Correct and verify
In staging, test normal routing, a stale client map, planned resharding, reconnect, and the intended multi-key operations. Verify bounded retries and a useful application error when an operation cannot meet placement rules. Confirm that all advertised endpoints remain reachable after failover. One successful read through a seed node does not establish a healthy cluster client.
Operating procedure
Monitor redirection errors by client version, destination reachability, and slot-placement failures by command family. Review key naming and script key declarations during application changes. Keep resharding acceptance checks in the runbook so temporary routing behavior receives the same attention as normal traffic.
Explore Clouvenix database administration for implementation and operational handover.