Redis Troubleshooting

Introduction

Redis problems often fall into a few categories—connection refused, memory maxed out, replication lag, Sentinel failover loops, or “works in redis-cli but not in app.” This chapter maps symptoms to diagnostics and fixes, with links to the chapters where each topic is taught.

Prerequisites

A running Redis instance or Docker container
Comfort with redis-cli and INFO

Diagnostic Flow

text

Symptom → ping/cli → INFO/memory → logs → fix one layer (config / client / ops)

Check	Command
Alive	`redis-cli ping` → `PONG`
Memory	`INFO memory`, `redis-cli --memkeys`
Slow commands	`SLOWLOG GET 10`
Big keys	`redis-cli --bigkeys`
Replication	`INFO replication`

Connection Issues

Connection refused

Cause: Redis not running, wrong host/port, firewall.

Fix:

bash

redis-cli -h 127.0.0.1 -p 6379 ping
sudo systemctl status redis
docker ps | grep redis

NOAUTH Authentication required

Cause: requirepass set; client missing password.

Fix:

bash

redis-cli -a yourpassword ping

Or AUTH after connect. Store password in env—not code.

Too many connections

Cause: Client pool leak; maxclients reached.

Fix:

bash

redis-cli INFO clients
redis-cli CLIENT LIST

Close idle clients; raise maxclients with care; fix connection pooling in app.

Memory Issues

OOM command not allowed (maxmemory)

Cause: maxmemory reached; policy noeviction.

Fix:

bash

redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET maxmemory-policy

Set policy allkeys-lru or raise limit—see expiration and memory.

Single big key

Cause: Huge Hash, giant List, unbounded Stream.

Fix:

bash

redis-cli --bigkeys
MEMORY USAGE mykey

Split key or archive data; cap Stream with XTRIM.

Performance

Slow responses

bash

redis-cli SLOWLOG GET 20
redis-cli LATENCY DOCTOR

Cause: KEYS *, large SMEMBERS, debug MONITOR in prod.

Fix: Replace KEYS with SCAN; use indexes/patterns from performance chapter.

High CPU, low QPS

Cause: Expensive commands, persistence fork (BGSAVE), AOF rewrite.

Check:

bash

redis-cli INFO persistence
redis-cli INFO stats

See persistence.

Replication

master_link_status

Cause: Network, wrong masterauth, master down.

Fix: INFO replication on replica; verify replicaof IP and password—replication chapter.

Stale reads on replica

Expected—replication is async. Use master for read-your-writes or monitor lag offset.

Sentinel and Cluster

Sentinel split-brain / flapping

Cause: Even number of Sentinels, network partition, wrong quorum.

Fix: Odd Sentinel count; review sentinel monitor quorum—Sentinel.

MOVED / ASK errors in cluster

Cause: Client not cluster-aware or slot migrating.

Fix: Use cluster-capable client; redis-cli -c—Cluster.

Application Layer

Cache always misses

TTL too short; wrong key; Redis DB index mismatch (-n 0 vs 1).

Lock never acquired

Key not released; wrong SET NX EX pattern—distributed lock project.

Spring cannot connect

application.yml host, password, SSL; Lettuce timeout—Spring integration.

Persistence and Recovery

Data gone after restart

No persistence enabled; ephemeral container without volume.

Fix: Enable RDB/AOF—persistence; mount data dir in Docker.

AOF rewrite failing

Disk full; permissions on appendonly.aof.

Quick Reference

Symptom	Likely cause	First action
Connection refused	server down	start redis / check port
OOM	maxmemory	INFO memory, policy
Slow	KEYS / bigkey	SLOWLOG, --bigkeys
Replica down	auth/network	INFO replication
502 app OK redis down	separate issue	ping redis from app host
Cluster MOVED	client	cluster client / -c

FAQ

redis-cli works, Java app fails?

Serialization, password, SSL, wrong database index.

Flush accidentally?

FLUSHALL—restore from RDB/AOF backup—MySQL backup mindset for ops discipline.

Docker Redis empty on restart?

Missing volume mount for /data.

Monitor in production?

MONITOR hurts performance—use sparingly.

Report doc typo?

Git fork workflow.

Planning doc?

frontend/gen_article_plan/redis.md.