Skip to content
DevOps AI ToolKit
Newsletter
Redis Troubleshooting Toolkit

Redis Troubleshooting Toolkit

Use this Redis troubleshooting toolkit to diagnose out-of-memory evictions, RDB/AOF persistence failures, replication and Sentinel failover, Cluster slot errors, and latency spikes.

Paste your error and get a triage plan.

Paste a log line, CLI error, stack trace, service failure, or config snippet and get a structured troubleshooting plan. Your snippet is carried straight into the AI Incident Response Assistant with Redis context prefilled.

Open the Redis Incident Assistant → Browse Redis prompts

Do not paste secrets, tokens, private keys, passwords, or customer data. Your snippet stays in your browser until you open the assistant.

Top 25 Redis Errors and Failure Modes

The production failures engineers hit most — each links to a full cause → fix → prevention guide.

OOM command not allowed when used memory > maxmemory

Redis has hit its maxmemory limit and rejects writes because no keys can be evicted under the current policy.

MISCONF Redis is configured to save RDB snapshots

A background save keeps failing so Redis refuses writes to protect against silent data loss on persistence errors.

MASTERDOWN link with master is down

A replica has lost its connection to the master and can no longer serve stale-read or write-forwarding traffic.

Replica full resync loop

A replica repeatedly triggers full RDB resyncs instead of partial sync, saturating the master and network.

CLUSTERDOWN hash slot not served

One or more of the 16384 cluster hash slots have no serving node, so the cluster rejects commands for those keys.

LOADING Redis is loading the dataset in memory

Redis is still loading its RDB or AOF file at startup and cannot serve client commands until loading completes.

READONLY You can't write against a read only replica

A write command reached a replica, typically after a failover or misrouted connection to the wrong node.

Connection refused

Clients cannot open a socket to Redis because the server is down, bound to the wrong interface, or blocked by a firewall.

ERR max number of clients reached

Redis has hit its maxclients limit and rejects new connections, usually from connection-pool leaks or too many clients.

Latency spikes and slow commands

Redis response times spike due to slow O(N) commands, fork stalls, swapping, or a saturated event loop.

WRONGTYPE Operation against a key holding the wrong kind of value

A command was run against a key whose data type does not match, such as GET on a hash or LPUSH on a string.

NOAUTH Authentication required

The client issued a command before authenticating against a password- or ACL-protected Redis instance.

WRONGPASS invalid username-password pair

Authentication failed because the supplied ACL username or password does not match the server configuration.

CROSSSLOT Keys in request don't hash to the same slot

A multi-key command in Redis Cluster spans keys that map to different hash slots and cannot be executed atomically.

MOVED redirect

The queried cluster node does not own the key's slot and redirects the client to the correct node for that slot.

ASK redirect

A slot is mid-migration between nodes, so the client is temporarily redirected with ASK for the keys being moved.

RDB/AOF load failed or corrupt file

Redis fails to start because its RDB snapshot or AOF file is truncated, corrupted, or version-incompatible.

High memory fragmentation ratio

The allocator holds far more memory than the dataset needs, inflating RSS and risking OOM under memory pressure.

Connection reset by peer

An established connection is abruptly closed by Redis due to timeouts, output-buffer limits, or a server restart.

EXECABORT Transaction discarded because of previous errors

A MULTI/EXEC transaction was aborted because a queued command failed to parse before EXEC was called.

BUSYGROUP Consumer Group name already exists

XGROUP CREATE failed because the stream consumer group already exists, common in non-idempotent setup scripts.

BUSY Redis is busy running a script

A long-running Lua script is blocking the single-threaded server, stalling all other clients until it finishes or is killed.

NOSCRIPT No matching script

EVALSHA referenced a script SHA that is no longer cached, typically after a restart or failover flushed the script cache.

Protocol error: invalid bulk length

Redis received malformed RESP protocol data, often from a non-Redis client, plaintext to a TLS port, or a corrupt pipeline.

BGSAVE / AOF rewrite fork failure (copy-on-write OOM) guide coming soon

Background save or AOF rewrite fails when fork cannot reserve copy-on-write memory, often due to overcommit settings.

Validate your config before you redeploy

Catch the structural mistakes that cause outages — 100% in your browser, nothing uploaded.

YAML Validator (redis.conf / manifests) Not sure? Start with the Incident Assistant →

Best Redis Prompts

Turn symptoms, logs, and config into a structured plan with prompts tuned for Redis.

Redis Memory Optimization

Shrink RSS and dataset footprint

Use this prompt

Redis Eviction Policy Tuning

Pick and tune maxmemory-policy

Use this prompt

Redis Persistence RDB/AOF Config

Design durable RDB and AOF settings

Use this prompt

Redis Replication Setup Review

Audit master/replica topology

Use this prompt

Redis Sentinel High Availability Design

Plan automatic failover with Sentinel

Use this prompt

Redis Cluster Sharding Design

Shard keyspace across cluster slots

Use this prompt

Redis Slowlog and Latency Analysis

Diagnose latency spikes and slow commands

Use this prompt

Redis Connection Pool Tuning

Fix max-clients and pool leaks

Use this prompt

Download the Redis Troubleshooting Runbook Pack

Checklists for a Redis instance under memory, persistence, replication, or latency pressure.

  • Memory & eviction (maxmemory) checks
  • RDB/AOF persistence recovery
  • Replication & Sentinel failover
  • Cluster slot & CLUSTERDOWN triage
  • Latency (SLOWLOG / LATENCY) diagnosis
Download the Redis Runbook Pack

All Redis Troubleshooting Guides

Grouped by failure-mode type — each guide covers cause, fix, validation, and prevention.

Authentication & TLS (5)

ERR Client sent AUTH, but no password is set NOPERM this user has no permissions DENIED Redis is running in protected mode NOAUTH Authentication required WRONGPASS invalid username-password pair or user is disabled

Networking (8)

ERR MULTI calls can not be nested bind: Address already in use EXEC without MULTI ASK <slot> <host:port> Could not connect to Redis ... Connection refused Connection reset by peer ERR max number of clients reached MOVED <slot> <host:port>

Storage (5)

Background append only file rewriting already in progress Latency Spikes — Fork, AOF Rewrite, THP and Swap via SLOWLOG/LATENCY MISCONF Redis is configured to save RDB snapshots but is currently unable to persist on disk Bad file format reading the append only file READONLY You can

Runtime (2)

Can Redis 'OOM command not allowed when used memory > maxmemory': How to Fix

Performance (2)

LOADING Redis is loading the dataset in memory High mem_fragmentation_ratio — RSS Far Exceeds used_memory

API errors (3)

TRYAGAIN Multiple keys request during rehashing of slot CROSSSLOT Keys in request don Protocol error: invalid bulk length / too big inline request

Configuration (5)

ERR invalid expire time in set command ERR syntax error ERR wrong number of arguments for command NOPROTO unsupported protocol version ERR unknown command

Other (20)

ERR Background save already in progress ERR DISCARD without MULTI ERR no such key NOGOODSLAVE No suitable replica to promote ERR value is not a valid float BUSYKEY Target key name already exists This instance has cluster support disabled DUMP payload version or checksum are wrong increment or decrement would overflow NOREPLICAS Not enough good replicas to write SELECT is not allowed in cluster mode ERR value is not an integer or out of range BUSY Redis is busy running a script BUSYGROUP Consumer Group name already exists CLUSTERDOWN Hash slot not served EXECABORT Transaction discarded because of previous errors MASTERDOWN Link with MASTER is down and replica-serve-stale-data is no NOSCRIPT No matching script. Please use EVAL Replica Stuck in Repeated Full Resync — Partial Resync Failing WRONGTYPE Operation against a key holding the wrong kind of value
Browse the full Redis category

Redis troubleshooting FAQ

Why is Redis using so much memory?
Redis memory is driven by your dataset plus overhead from data-structure encodings, client output buffers, replication backlog, and allocator fragmentation. Run INFO memory and check used_memory versus used_memory_rss and mem_fragmentation_ratio to separate real data from fragmentation. Large values, missing TTLs, and inefficient encodings (for example small hashes exceeding hash-max-listpack-entries) inflate usage. Set a maxmemory limit with an appropriate eviction policy and use MEMORY USAGE or redis-cli --bigkeys to find the worst offenders.
How do I fix "MISCONF Redis is configured to save RDB snapshots"?
This error means a background save keeps failing, so Redis stops accepting writes to avoid silent data loss. The usual causes are a full disk, wrong permissions on the dir/dbfilename path, or fork failing because of memory overcommit. Check the Redis log and INFO persistence for rdb_last_bgsave_status, free up disk, fix directory permissions, and set vm.overcommit_memory=1 on the host. As a temporary unblock you can set stop-writes-on-bgsave-error no, but fix the underlying save failure rather than leaving it disabled.
How do I recover from a Redis replication break?
First check INFO replication on both nodes for master_link_status and the last I/O time to confirm the link is actually down. Common causes are network partitions, an undersized repl-backlog-size forcing full resyncs, or an output-buffer limit killing the replica connection. Raise client-output-buffer-limit for replicas and increase the backlog so partial resync can resume instead of a full sync. If the replica is stuck in a full-resync loop, verify disk space and RDB save health on the master, since each resync depends on a successful background save.
Why is my Redis latency spiking?
Latency spikes usually come from slow O(N) commands (KEYS, large HGETALL, SMEMBERS), fork pauses during RDB/AOF rewrites, memory swapping, or a saturated single-threaded event loop. Use SLOWLOG GET and the LATENCY DOCTOR / LATENCY HISTORY commands to pinpoint the source. Replace blocking commands with SCAN and pipelining, disable transparent huge pages, and ensure the instance is not swapping. If forks are the cause, tune save points and AOF rewrite thresholds or offload persistence to a replica.
When should I use Redis Cluster vs Sentinel?
Use Sentinel when a single primary can hold your whole dataset and you only need automatic failover and high availability. Use Redis Cluster when the dataset or write throughput is too large for one node and you need to shard data horizontally across the 16384 hash slots. Cluster adds complexity: clients must be cluster-aware, multi-key operations require the same hash slot (or hash tags), and cross-slot commands are restricted. If you do not need sharding, Sentinel is simpler and avoids CROSSSLOT and MOVED/ASK considerations.
How do I stop Redis from evicting keys or throwing OOM errors?
OOM errors mean used memory reached maxmemory and the eviction policy could not free space, often because it is set to noeviction or all keys lack TTLs. Decide whether Redis is a cache or a datastore: for a cache use allkeys-lru or allkeys-lfu so cold keys are evicted, and for a datastore add capacity or shard rather than evicting. Set TTLs on cache keys so volatile-* policies have candidates to reclaim. Monitor evicted_keys and used_memory in INFO, and right-size maxmemory to leave headroom for fork copy-on-write during saves.