Redis Common Errors and Fixes with Practical Examples

Intro

Redis errors typically surface during moments of pressure: a sudden timeout, a full memory warning, or a replica that stops syncing. This guide covers common Redis errors and fixes with practical, copy-paste examples. It is written for developers, DevOps engineers, and technical startup teams who need to move from an observed problem to a verified result without guessing.

You will learn how to inventory your Redis version and topology, safely change configuration, use built-in diagnostics, recover from failures, and avoid the most frequent operational mistakes. Every section includes real commands, expected output, failure signals, and a verification step. The approach is operational: observe before changing, limit the blast radius, use placeholders instead of secrets, and document recovery before you need it.

How to Use This Guide

Each procedure follows the same practical pattern:

• Observe. Run a read-only command to capture the current state.
• Interpret. Compare the output against the expected signal.
• Change (if needed). Apply the smallest justified configuration change.
• Verify. Confirm the new state with another read-only command.
• Recover. Know the exact rollback path if verification fails.

All examples assume Redis 5.0 or later, but most commands work on older versions. Where a version matters, it is stated explicitly.

Version and Environment Inventory

Before touching anything, know exactly what you are running. A large share of Redis troubleshooting dead-ends happen because the operator misidentifies the version, the topology, or the component that is actually failing. Redis fixes often fail because they are applied to the wrong process or the wrong configuration file.

Step 1: Identify the Installed Redis Version

Connect to the Redis instance and run:

redis-cli INFO server

Look for the redis_version field:

redis_version:7.2.4

If you use Docker, get the image tag:

docker inspect --format '{{.Config.Image}}' <container-name>

Example output:

redis:7.2-alpine

Prerequisite: redis-cli must be able to connect. If the instance requires a password, use redis-cli -a '<password>' INFO server or set the REDISCLI_AUTH environment variable. Never paste real credentials in a shared document; use a placeholder like <password>.

Step 2: Capture the Deployment Topology

Determine if you are running standalone, sentinel, or cluster mode. For standalone and sentinel-managed instances, run:

redis-cli INFO replication

Expected output for a standalone primary:

role:master
connected_slaves:0

For a replica:

role:slave
master_host:10.0.0.5
master_port:6379
master_link_status:up

For Redis Cluster, use:

redis-cli CLUSTER INFO

The first line shows cluster_state:ok when healthy. If it says cluster_state:fail, proceed to the failure modes section.

Step 3: Record Read-Only Observability Data

Capture timestamps and current state for later comparison:

date -u +"%Y-%m-%dT%H:%M:%SZ"
redis-cli INFO stats | grep -E 'total_connections_received|total_commands_processed|instantaneous_ops_per_sec'
redis-cli CONFIG GET maxmemory maxmemory-policy

Example output:

2025-03-21T10:32:15Z
total_connections_received:4231
total_commands_processed:8923401
instantaneous_ops_per_sec:540
maxmemory:0
maxmemory-policy:noeviction

Store this snapshot in your incident notes. It is your baseline for post-change verification.

What Can Go Wrong

• Wrong Redis binary. Running redis-cli from your laptop against a server can lead to version mismatch. Always run redis-cli --version first and compare.
• Connecting to the wrong database. By default, Redis uses database 0. If your application writes to database 3, a KEYS * on database 0 shows nothing. Use SELECT 3 before inspection.
• Missing authentication. If the server requires a password, redis-cli INFO returns NOAUTH Authentication required. Fix it with redis-cli -a '<password>' or set requirepass temporarily only in a test environment.

Safe Configuration Path

Configuration changes are a leading cause of Redis incidents. The safe path is: inspect the current setting, test the change in a staging environment, apply it in production with a rollback plan, and verify the result. Never edit the configuration file directly as your first move.

Read the Current Configuration

All runtime configuration is available via CONFIG GET:

redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET save
redis-cli CONFIG GET appendonly

Example output:

maxmemory
0
save
3600 1 300 100 60 10000
appendonly
no

The save directives mean: save after 3600 seconds if at least 1 key changed, after 300 seconds if at least 100 keys changed, after 60 seconds if at least 10000 keys changed.

Make a Small, Justified Change

Suppose your monitoring shows memory usage approaching the server's physical RAM. You want to set maxmemory to 4 GB and use allkeys-lru eviction. First, check the current maxmemory:

redis-cli CONFIG GET maxmemory

Output: maxmemory 0 (unlimited).

Then apply the change at runtime:

redis-cli CONFIG SET maxmemory 4gb
redis-cli CONFIG SET maxmemory-policy allkeys-lru

Expected output:

OK
OK

Now verify:

redis-cli CONFIG GET maxmemory maxmemory-policy

Output:

maxmemory
4294967296
maxmemory-policy
allkeys-lru

Blast radius: This setting only affects the connected instance. In a sentinel or cluster setup, you must apply it to every node. In a replica set, apply it to the master first, then to each replica.

Rollback: If the eviction policy causes unexpected key loss, revert immediately:

redis-cli CONFIG SET maxmemory 0
redis-cli CONFIG SET maxmemory-policy noeviction

Verify with CONFIG GET again.

Persisting the Change

Runtime changes are lost after a restart. To make them permanent, update the Redis configuration file. Find its path:

redis-cli CONFIG GET dir
redis-cli CONFIG GET config_file

Example output:

dir
/var/lib/redis
config_file
/etc/redis/redis.conf

Use sed or your editor to change the values. For example:

sudo sed -i 's/^# maxmemory <bytes>/maxmemory 4gb/' /etc/redis/redis.conf
sudo sed -i 's/^# maxmemory-policy noeviction/maxmemory-policy allkeys-lru/' /etc/redis/redis.conf

Then restart Redis safely. Test the configuration first:

redis-server /etc/redis/redis.conf --test-memory 4096mb

If the test passes, restart the service:

sudo systemctl restart redis-server

Verify the setting survived:

redis-cli CONFIG GET maxmemory maxmemory-policy

Never use real credentials in config examples. If you set requirepass, use a placeholder like your-strong-password and rotate it regularly.

Verification and Diagnostics

Diagnosing Redis issues requires separating symptoms from root causes. Use Redis's built-in INFO, SLOWLOG, LATENCY, and MONITOR commands judiciously. Each command has a cost, so run them only when needed.

Check Overall Health with INFO

The INFO command returns dozens of metrics. Focus on sections relevant to your issue:

redis-cli INFO

Key fields to watch:

• connected_clients: Number of current connections. A sudden spike can indicate a connection leak in your application.
• used_memory_human: Current memory usage.
• maxmemory_human: Configured limit.
• total_net_input_bytes / total_net_output_bytes: Network throughput.
• keyspace_hits / keyspace_misses: Cache efficiency. A low hit ratio suggests a poor key design.
• rejected_connections: Number of connections rejected due to maxclients. If nonzero, increase maxclients or fix the client leak.

Example partial output:

# Memory
used_memory:1024000
used_memory_human:1.00M
maxmemory:4294967296
maxmemory_human:4.00G
# Stats
total_connections_received:5021
total_commands_processed:10234987
rejected_connections:0
keyspace_hits:982341
keyspace_misses:10234

Identify Slow Commands with SLOWLOG

Slow commands degrade performance. Check the slowlog:

redis-cli SLOWLOG GET 10

Example output:

1) 1) (integer) 3
   2) (integer) 1711026000
   3) (integer) 1520
   4) 1) "KEYS"
      2) "customer:*"
   5) "127.0.0.1:54321"
   6) ""

This shows a KEYS customer:* command took 1520 microseconds. In production, KEYS can block Redis for seconds if there are many keys. Replace it with SCAN.

Configure the slowlog threshold to catch slower commands:

redis-cli CONFIG SET slowlog-log-slower-than 10000

This logs commands slower than 10 milliseconds.

Diagnose Latency Spikes with LATENCY

Redis provides a latency monitor. Enable it with a threshold:

redis-cli CONFIG SET latency-monitor-threshold 100

Then after some activity, check latency events:

redis-cli LATENCY LATEST

Example output:

1) 1) "command"
   2) (integer) 1711026000
   3) (integer) 250
   4) (integer) 100

This shows a command took 250 ms, exceeding the 100 ms threshold. Use LATENCY HISTORY command for a time series.

Caution: MONITOR streams every command, which can impact performance. Use it only for short debugging sessions, never in production under load.

Inspecting Client Connections

A common error is misconfigured client timeouts. See active clients:

redis-cli CLIENT LIST

Example line:

id=123 addr=10.0.0.8:56789 fd=8 name=app-server age=3600 idle=320 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=0 qbuf-free=0 obl=0 oll=0 omem=0 events=r cmd=get

The age is total connection time, idle is time since last command. Many connections with high idle may indicate a client that is not closing connections properly.

Failure Modes and Recovery

Redis failures cluster into a few patterns: memory exhaustion, persistence errors, replication breakdown, and network/connection problems. Each section gives the error, diagnosis, fix, and rollback.

1. OOM (Out of Memory) Errors

Error message:

OOM command not allowed when used memory > 'maxmemory'

This means Redis has reached the maxmemory limit and the eviction policy cannot free memory (usually noeviction).

Diagnosis:

redis-cli INFO memory

Compare used_memory_human with maxmemory_human. If they are equal or close, you are at the limit.

Fix (choose one):

1. Evict less important keys by setting an eviction policy:

   redis-cli CONFIG SET maxmemory-policy allkeys-lru

1. Increase maxmemory if the server has spare RAM:

   redis-cli CONFIG SET maxmemory 8gb

1. Delete unused keys manually: use SCAN and DEL for specific patterns.

Verification:

redis-cli INFO memory | grep used_memory_human
redis-cli CONFIG GET maxmemory-policy

Rollback: If eviction causes data loss you cannot accept, set policy back to noeviction and scale memory.

2. Persistence Errors

Redis persists data via RDB snapshots and/or AOF logs. Failures can lead to data loss.

Error message examples:

MISCONF Redis is configured to save RDB snapshots, but it is currently unable to persist on disk

Diagnosis:

redis-cli INFO persistence

Look for rdb_last_bgsave_status:err or aof_last_write_status:err. Check disk space:

df -h /var/lib/redis

Fix:

• If disk full, free space or change the dir to a larger volume.
• Check permissions on the dir and dbfilename:

  ls -ld /var/lib/redis

The Redis user must have write permission.

• If RDB saving fails frequently, adjust save intervals or disable RDB temporarily (not recommended for production).
• For AOF errors, check the AOF file for corruption and consider redis-check-aof --fix.

Verification:

redis-cli INFO persistence | grep rdb_last_bgsave_status

Expected: rdb_last_bgsave_status:ok.

3. Replication Issues

Error message:

MASTER down

or the replica's master_link_status is down.

Diagnosis:

On the replica:

redis-cli INFO replication

Check master_link_status. If down, review master_host, master_port, and connectivity:

redis-cli -h <master-host> -p 6379 PING

Fix:

• Ensure network connectivity (firewall, security groups).
• Correct the replica's configuration: replicaof <master-host> <master-port>.
• If authentication is enabled, set masterauth on the replica.
• If the replica was promoted manually, demote it back or reset the topology.

Verification:

redis-cli INFO replication | grep master_link_status

Expected: master_link_status:up.

4. Connection Timeouts and Refusals

Error message:

Could not connect to Redis at 127.0.0.1:6379: Connection refused

This means the Redis server is not running or not listening on that address.

Diagnosis:

redis-cli PING

If refused, check the service:

sudo systemctl status redis-server

If running, check bind and port:

redis-cli CONFIG GET bind port

Fix:

• Start the service: sudo systemctl start redis-server.
• If the bind address is wrong, adjust it in the config file and restart.
• If using Docker, ensure the port mapping is correct: -p 6379:6379.

Verification:

redis-cli PING

Expected: PONG.

5. Client Errors: MAXCLIENTS Reached

Error message:

ERR max number of clients reached

Diagnosis:

redis-cli INFO clients

Compare connected_clients to maxclients.

Fix:

• Increase maxclients:

  redis-cli CONFIG SET maxclients 20000

• Find and fix client connection leaks in your application. Use CLIENT LIST to identify offenders.

Verification:

redis-cli CONFIG GET maxclients

Operations Checklist

Use this checklist before and after any Redis change. Assign each item to a single owner and revisit the checklist during every incident review.

Each owner is accountable for completing their item and reporting the outcome in the weekly operations meeting.

Common Pitfalls and Mistakes

The following mistakes recur in Redis deployments. Understand why they happen and how to avoid them.

1. Using KEYS in Production

Why it happens: Developers test with small datasets and KEYS is convenient. In production, it blocks the single-threaded Redis server for every matching key, causing latency spikes.

How to avoid: Use SCAN with a cursor for non-blocking iteration, e.g., redis-cli --scan --pattern 'customer:*'. If you absolutely need to delete matching keys, use UNLINK instead of DEL to avoid blocking.

2. Ignoring Persistence Settings

Why it happens: Developers rely on default settings and assume data will survive a restart. But default save intervals can cause data loss if the process crashes between snapshots.

How to avoid: Configure a trade-off between performance and durability. For minimal data loss, use append-only file (AOF) with appendfsync everysec. For critical data, consider appendfsync always (with performance cost). Test your recovery from RDB and AOF regularly.

3. Setting maxmemory to 0

Why it happens: The default maxmemory 0 means no limit, which is fine for development but dangerous in production. When Redis uses all memory, the operating system's OOM killer may terminate Redis or other processes.

How to avoid: Always set maxmemory to a value below the server's physical RAM, leaving room for the OS. Monitor the ratio of used_memory to maxmemory.

4. Running Redis Without Authentication on a Public Interface

Why it happens: Default configuration binds to all interfaces and has no password. Security is an afterthought in internal testing, but many instances are accidentally exposed to the internet, leading to data theft or ransomware.

How to avoid: Bind to a private interface (bind 10.0.0.5), set requirepass with a strong password, and use firewall rules or security groups to restrict access. Prefer TLS for network encryption.

5. Misconfiguring Replication

Why it happens: Copying a config file from the master to a replica without changing replicaof results in two independent masters or a replication loop.

How to avoid: Always verify INFO replication on both nodes. On the replica, ensure replicaof <master-ip> <master-port> is set and masterauth matches the master's requirepass. Use redis-cli SLAVEOF NO ONE only when promoting a replica intentionally.

6. Neglecting Slowlog and Latency Monitoring

Why it happens: Teams focus on functional errors and ignore performance until users complain. Slow commands may not fail but degrade the entire application.

How to avoid: Enable slowlog (e.g., slowlog-log-slower-than 10000) and latency monitor (latency-monitor-threshold 100). Review them regularly and after any code deployment.

Conclusion

Redis common errors are usually not mysterious. They follow from misconfiguration, resource exhaustion, or incorrect client behavior. The fixes in this guide are practical and version-scoped, but they only work if you observe before changing and verify after changing.

Start with the Version and Environment Inventory to know your baseline. Make only the smallest justified change using the Safe Configuration Path. Use the Verification and Diagnostics commands to confirm the fix. For each failure mode in this article, practice the recovery steps in a staging environment before you need them in production.

Finally, adopt the Operations Checklist and assign a single owner to each item. Redis runs well when it is operated with discipline. Choose one low-risk verification from this guide today, run the documented command, and compare the result against the expected output. If the output matches, you have just improved the reliability of your Redis deployment.

Review your Redis setup monthly: revisit maxmemory, maxclients, persistence settings, and replication health. A reliable Redis is not an accident; it is the result of consistent, observable operations.