Redis Configuration Mistakes with Practical Examples

Intro

Redis is often treated as a simple key-value store, but its configuration has enough sharp edges to cause data loss, performance cliffs, and security holes. Common mistakes include unprotected network exposure, unbounded memory, disabled persistence, and unsafe eviction policies. The goal of this article is to help developers and operators move from noticing a problem to verifying a fix, using concrete commands and expected outputs.

We will cover version and environment inventory, safe configuration workflows, verification and diagnostics, failure modes, and an operations checklist. Every example includes a read-only observation, the smallest justified change, and a recovery path. We will use placeholders like <your-host> and <your-password> instead of real values.

This article assumes you have access to a Redis server (version 6.0 or later), the redis-cli tool, and basic shell skills. If you are using Docker, the commands should be run inside the container's shell.

Version and Environment Inventory

Before changing any setting, confirm exactly what you are running. Redis behavior changes between versions; a configuration that works on 5.x may be renamed or deprecated on 7.x. For example, CONFIG SET save was removed in Redis 7.0 and replaced by CONFIG SET save with different syntax; using the old command fails immediately.

Example 1.1: Identify installed Redis version

Command:

redis-server --version

Expected output:

Redis server v=7.2.4 sha=00000000:0 malloc=jemalloc-5.3.0 bits=64 build=...

Prerequisite: redis-server binary is in your PATH.

Blast radius: read-only, no impact.

Verification: the first two digits of the version (e.g., 7.2) match what your application expects.

Recovery: not needed.

Example 1.2: Check current configuration with CLI

Command:

redis-cli -h <your-host> -p <your-port> INFO server

Expected output (excerpt):

# Server
redis_version:7.2.4
redis_mode:standalone
os:Linux 5.15.0-91-generic x86_64
arch_bits:64
process_id:1234
tcp_port:6379
uptime_in_seconds:86400

Prerequisite: you know the host and port, and the server is reachable.

Blast radius: read-only.

Verification: redis_version and redis_mode match your expectation (standalone, sentinel, or cluster).

Recovery: not needed.

Why this matters: if you apply a parameter that only exists in Redis 7 to a Redis 6 server, the server may fail to start. Always pin your version in documentation and in your infrastructure code.

Safe Configuration Path

A safe configuration change follows a predictable sequence: observe, backup, change one parameter, verify, and know how to roll back. The master config file is usually /etc/redis/redis.conf or /usr/local/etc/redis.conf, but Redis also supports runtime changes via CONFIG SET. Runtime changes are lost on restart unless you persist them with CONFIG REWRITE.

Example 2.1: Change maxmemory at runtime

Observation:

redis-cli CONFIG GET maxmemory

Output:

1) "maxmemory"
2) "0"

(0 means no memory limit, which can lead to the OS swapping or the OOM killer stopping Redis.)

Intervention: set a limit of 2 GB:

redis-cli CONFIG SET maxmemory 2gb

Expected output:

OK

Verify:

redis-cli CONFIG GET maxmemory

Output:

1) "maxmemory"
2) "2147483648"

Blast radius: affects memory usage but not data. If the limit is too low, writes may fail.

Recovery: reset to previous value:

redis-cli CONFIG SET maxmemory 0

To make the change permanent, either edit the config file and restart, or run:

redis-cli CONFIG REWRITE

Example 2.2: Set appendonly in config file

Open the config file with an editor:

# /etc/redis/redis.conf
appendonly no

Change to appendonly yes and add appendfsync everysec for reasonable durability.

Restart Redis:

sudo systemctl restart redis

Verify persistence is active:

redis-cli CONFIG GET appendonly

Output:

1) "appendonly"
2) "yes"

Blast radius: enabling AOF increases disk I/O. If the disk is slow, latency may rise.

Recovery: revert the change and restart.

When changing multiple parameters, make one change at a time. If something breaks, you will know which parameter caused it.

Verification and Diagnostics

Verification means checking that the configured behavior actually occurs, not just that the command returned OK. Redis provides several built-in diagnostic commands.

Example 3.1: Check memory usage and eviction policy

Command:

redis-cli INFO memory

Expected output (excerpt):

# Memory
used_memory:1048576
used_memory_human:1.00M
used_memory_rss:2097152
maxmemory:2147483648
maxmemory_human:2.00G
maxmemory_policy:noeviction

If maxmemory_policy is noeviction and used_memory reaches maxmemory, write commands will fail with OOM command not allowed when used memory > 'maxmemory'. To allow eviction, set an appropriate policy, for example:

redis-cli CONFIG SET maxmemory-policy allkeys-lru

Verify:

redis-cli CONFIG GET maxmemory-policy

Output:

1) "maxmemory-policy"
2) "allkeys-lru"

Example 3.2: Diagnose slow operations with SLOWLOG

If requests are slow, check the slow log:

redis-cli SLOWLOG GET 10

Output (excerpt):

1) 1) (integer) 1
   2) (integer) 1700000000
   3) (integer) 5000
   4) 1) "KEYS"
      2) "*"
   5) "127.0.0.1:45678"
   6) ""

A KEYS * command taking 5000 microseconds (5 ms) is a red flag. Replace it with SCAN in production code. The command SLOWLOG RESET clears the log for a clean state.

Example 3.3: Verify client connections and identify blockers

redis-cli CLIENT LIST

Output (excerpt):

id=3 addr=127.0.0.1:56789 fd=8 name= age=123 idle=0 flags=N db=0 sub=0 psub=0 multi=-1 qbuf=0 qbuf-free=0 obl=0 oll=0 omem=0 events=r cmd=client

Look for clients with high omem (output buffer memory) or high age with no activity. They may be stuck.

Common Mistakes and How to Avoid Them

Here are frequent configuration mistakes, why they happen, and how to avoid or recover from them.

Mistake 1: Binding to all interfaces without a password

Default Redis config often has bind 0.0.0.0 and no requirepass. This exposes Redis to the public internet. Attackers can read all data or use Redis to write files (like SSH keys).

Why it happens: developers assume bind 127.0.0.1 is default or that a firewall protects the port.

How to avoid: explicitly set bind to a private IP or localhost, and set a strong requirepass. Example:

bind 127.0.0.1
requirepass <your-strong-password>
protected-mode yes

Then restart and test:

redis-cli -h <your-host> -p <your-port> -a <your-password> PING

Expected: PONG.

Recovery: if you cannot restart, use CONFIG SET requirepass <password> immediately, but note clients must re-authenticate.

Mistake 2: Leaving maxmemory unset and maxmemory-policy as noeviction

In production, infinite memory growth leads to system swapping or OOM kill. If eviction is disabled, Redis returns errors when memory is full, causing application failures.

Why it happens: developers focus on functionality and forget capacity planning.

How to avoid: set maxmemory to about 70-80% of available RAM, and choose an eviction policy based on data usage. For a cache, use allkeys-lru. For a session store, volatile-lru might be safer. Verify with INFO memory.

Mistake 3: Disabling persistence

Without RDB or AOF, a restart causes total data loss. Many assume Redis is only a cache, but often it holds important data.

Why it happens: default config may have persistence disabled, or developers disable it for speed without understanding the impact.

How to avoid: enable at least one persistence method. For most use cases, AOF with appendfsync everysec is recommended. Verify by checking CONFIG GET appendonly and CONFIG GET save.

Mistake 4: Using KEYS pattern in production

KEYS * blocks the server while scanning the entire keyspace, causing latency spikes for all clients.

Why it happens: it is the simplest way to list keys, and works fine on small datasets.

How to avoid: use SCAN with a cursor, which iterates incrementally. Update application code before data grows.

Mistake 5: Ignoring client output buffer limits

If a client is slow to read, Redis buffers output to that client. Unbounded buffers can consume all memory, causing the server to kill connections or crash.

Why it happens: defaults may be too high for high-throughput scenarios, or a client subscribes to a busy channel and stops reading.

How to avoid: set client-output-buffer-limit for normal and pubsub clients. Example:

client-output-buffer-limit normal 0 0 0
client-output-buffer-limit pubsub 32mb 8mb 60

This limits pubsub clients to 32 MB hard limit, 8 MB soft limit for 60 seconds. Monitor with CLIENT LIST and INFO clients.

Failure Modes and Recovery

Configuration changes can fail in visible or hidden ways. Here are common failure modes and how to recover.

Failure 1: Server fails to start after editing config file

Symptom: systemctl status redis shows failed, and logs show a parse error.

Cause: typo or unsupported directive.

Recovery: check logs with sudo journalctl -u redis, fix the line, and restart. If needed, restore from a backup config file. Always keep a known-good config backup, e.g., /etc/redis/redis.conf.bak.

Failure 2: CONFIG SET succeeded but setting lost on restart

Symptom: after restart, the setting reverts to old value.

Cause: CONFIG SET only affects runtime; you forgot CONFIG REWRITE or editing the config file.

Recovery: apply the setting again and persist it with CONFIG REWRITE, or manually edit the config file and restart.

Failure 3: Authentication failure after setting requirepass

Symptom: clients get NOAUTH Authentication required.

Cause: clients not updated with new password.

Recovery: update client connection strings. For redis-cli, use -a <password> or AUTH <password> command.

Failure 4: Memory eviction causes data loss

Symptom: INFO stats shows evicted_keys increasing, and some keys disappear.

Cause: eviction policy too aggressive or maxmemory set too low.

Recovery: increase maxmemory or change policy to noeviction temporarily to stop evictions, but be aware writes may fail. Investigate data access patterns and adjust.

Failure 5: AOF file corruption

Symptom: Redis refuses to start or load data, log shows Bad file format reading the append only file.

Cause: disk full, power loss, or bug.

Recovery: use redis-check-aof --fix <aof-file> to attempt repair, or restore from a recent RDB snapshot. Always have a backup strategy.

Operations Checklist

Use this checklist every time you change Redis configuration. It assumes a single accountable owner for each decision (e.g., the DevOps engineer on call for infrastructure changes, or the tech lead for application-related settings). Revisit these decisions monthly or after any significant traffic change.

1. Identify version and topology

• Owner: DevOps engineer (e.g., Priya Shah)
• Command: redis-server --version and INFO server
• Expected: version matches documented baseline, topology correct.
• Revisit: every deployment or monthly audit.

1. Backup current configuration

• Owner: same as above
• Command: redis-cli CONFIG GET '*' > redis-config-backup-$(date +%F).txt
• Also copy the config file: cp /etc/redis/redis.conf /etc/redis/redis.conf.bak
• Expected: backup file exists and is non-empty.

1. Make a single change with a documented rollback

• Owner: same
• Example: CONFIG SET maxmemory 2gb with rollback CONFIG SET maxmemory 0
• Expected: OK

1. Verify the change took effect

• Owner: same
• Command: CONFIG GET maxmemory and relevant INFO sections.
• Expected: value matches intended setting.

1. Persist the change if needed

• Owner: same
• Command: CONFIG REWRITE or edit config file.
• Expected: after restart, setting remains.

1. Monitor for side effects

• Owner: SRE or monitoring team (e.g., Marcus Chen)
• Command: redis-cli INFO stats and SLOWLOG GET
• Expected: no unusual errors, latency stable.
• Revisit: continuously via monitoring alerts.

1. Document the change

• Owner: person making the change
• Record in change log: what, why, when, rollback procedure.

1. Review dependency impacts

• Owner: tech lead (e.g., Elena Rodriguez)
• Consider clients, Node.js connection pools, Docker health checks, monitoring scrapers.
• Expected: all dependent systems still function.
• Revisit: after each change.

Conclusion

Redis configuration mistakes are common but avoidable. By inventorying your environment, making incremental changes, verifying with concrete commands, and having recovery plans, you can prevent outages and data loss. The key is to treat Redis configuration with the same rigor as application code: versioned, tested, and reviewed.

Start with a low-risk change: check your current maxmemory and eviction policy, set a sensible limit, and verify with INFO memory. Record the before and after, and document how to revert. As you gain confidence, address other areas like persistence, security, and client buffers.

A reliable Redis operation makes failure visible, protects sensitive data, limits the blast radius of changes, and defines recovery before an incident demands it.