Troubleshooting Common Issues
1. Debugging Connection Timeouts
| Cause | Resolution |
|---|---|
| Pool exhaustion | Increase pool size; check leaks (unclosed connections) |
timeout directive too low | Tune server timeout and client socket timeout |
| Latency spike | LATENCY DOCTOR; disable THP; raise tcp-keepalive |
2. Resolving Memory Overflow Errors
| Symptom | Action |
|---|---|
| High fragmentation | Enable activedefrag yes |
| Unbounded growth | Set TTLs; switch to eviction policy |
| Large keys | redis-cli --bigkeys; split or move out |
3. Handling Out-of-Memory Errors
| Error | Cause |
|---|---|
| OOM command not allowed | noeviction policy + maxmemory hit |
| MISCONF | BGSAVE failed and stop-writes enabled |
| Fix | Choose appropriate eviction policy or raise maxmemory |
4. Handling Slow Query Performance
| Diagnosis | Action |
|---|---|
SLOWLOG GET | Identify O(N) commands |
INFO commandstats | Find hotspots |
| Replace | KEYS→SCAN; large HGETALL→HSCAN |
5. Fixing Replication Lag
| Cause | Action |
|---|---|
| Slow replica disk | Faster storage or diskless replication |
| Backlog too small | Increase repl-backlog-size |
| Network saturation | Increase bandwidth or reduce write rate |
| Big keys | Split — they block replication stream |
6. Resolving Cluster Split-Brain
| Mitigation | Detail |
|---|---|
cluster-require-full-coverage yes | Refuse writes when partial |
min-replicas-to-write | Reject writes if too few replicas |
| Avoid manual TAKEOVER | Last-resort only |
7. Debugging Cluster Node Failures
| Step | Command |
|---|---|
| Topology | CLUSTER NODES |
| Health | redis-cli --cluster check |
| Links | CLUSTER LINKS 7.0+ |
| Force forget | CLUSTER FORGET node-id |
8. Debugging Lua Script Errors
| Error | Action |
|---|---|
| BUSY script timeout | SCRIPT KILL if no writes done; else SHUTDOWN NOSAVE |
| NOSCRIPT | Reload via SCRIPT LOAD |
| Replication note | Use redis.replicate_commands() (default in 7.x) |
9. Fixing Persistence Failures
| Cause | Action |
|---|---|
| No disk space | Free space; check dir |
| fork() failure | Set vm.overcommit_memory=1 |
| Permissions | Ensure redis user owns data dir |
10. Resolving AOF Corruption
redis-check-aof --fix appendonlydir/appendonly.aof.1.incr.aof| Option | Effect |
|---|---|
aof-load-truncated yes | Start despite tail truncation |
--fix | Truncate to last valid command |
11. Debugging Client Blocking Issues
| Diagnosis | Action |
|---|---|
CLIENT LIST | Look for cmd=blpop, large obl/oll |
CLIENT UNBLOCK id | Release a blocked client |
| Backpressure | Increase client-output-buffer-limit carefully |
12. Fixing Network Connectivity Issues
| Check | Tool |
|---|---|
| Reachability | redis-cli -h host ping |
| Port open | nc -vz host 6379 |
| TLS handshake | openssl s_client -connect host:6379 |
| Firewall | Verify security groups / iptables |
13. Resolving Authentication Failures
| Error | Cause |
|---|---|
| NOAUTH | Missing AUTH after connect — send before any command |
| WRONGPASS | Check requirepass / ACL password |
| NOPERM | ACL denies command/key/channel — adjust SETUSER |
14. Handling Eviction Policy Issues
| Symptom | Action |
|---|---|
| Hot keys evicted | Switch to LFU; raise maxmemory-samples |
| Latency spikes during eviction | Enable lazyfree-lazy-eviction yes |
| OOM despite eviction | Verify maxmemory-policy not noeviction |