Redis MISCONF unable to persist on disk: a 5-minute recovery runbook

Redis MISCONF RDB snapshots error: a 5-minute emergency recovery runbook (diagnose by cause)

MISCONF Redis is configured to save RDB snapshots, but it is
currently unable to persist on disk. Commands that may modify the
data set are disabled, because this instance is configured to report
errors during writes if RDB snapshotting fails.

If you landed here by pasting that exact error into Google, take a breath. Writes are blocked and it feels urgent, but this is not an OOM and Redis is not down. Redis is still running and reads (GET) work fine. What failed is persisting an RDB snapshot to disk (BGSAVE), and because stop-writes-on-bgsave-error yes is set, Redis is refusing write commands like SET/LPUSH/INCR: "if I cannot save, I will not accept writes."

This post keeps theory to a minimum and follows command → interpret the result → next action. Copy-paste in order.

Step 1: Restore writes immediately (temporary workaround)

Put root-cause analysis on hold and stop the bleeding first. This one line restores writes immediately.

redis-cli CONFIG SET stop-writes-on-bgsave-error no

You should see OK, and SET/LPUSH that were failing will go through again. If auth is enabled, add redis-cli -a <password> or -h <host> -p <port>.

🔴 Warning: this is only a painkiller. This setting means "keep going quietly even if RDB saves keep failing." Disk persistence is still broken, and if Redis restarts in this state you will lose everything after the last successful snapshot. You must find the root cause in steps 2–3 below, then flip it back to yes in step 5. Stop here and the next incident is data evaporation.

Step 2: Three-way root-cause diagnostic table

In practice, MISCONF almost always comes down to one of three causes. Find your log line in the table below.

Step 3: Copy-paste diagnostic flow

Pin down which branch you are on with commands. Run them in order.

# (1) Check persistence status — failure flag and last successful save time
redis-cli INFO persistence | grep -E \
  "rdb_last_bgsave_status|rdb_last_save_time|aof_last_bgrewrite_status"

rdb_last_bgsave_status:err confirms it. Convert rdb_last_save_time to a human-readable time to see when the last successful snapshot ran (date -d @<value>).

# (2) Check free space on the RDB save path → identify cause ①
RDB_DIR=$(redis-cli CONFIG GET dir | tail -1)
echo "dir = $RDB_DIR"
df -h "$RDB_DIR"

# (3) Check path exists and permissions → identify cause ① or ③
ls -ld "$RDB_DIR"

If df shows Use% at 100%, that is cause ① (disk full). If ls shows an owner other than redis, or the path is missing, that is ① or ③.

# (4) Pull the underlying error from system logs
journalctl -u redis -n 50 --no-pager | grep -iE "background saving|fork|space|permission"
# If not systemd:
grep -iE "Background saving error|fork|No space" /var/log/redis/redis-server.log | tail -20

If you see fork: Cannot allocate memory and cat /proc/sys/vm/overcommit_memory is 0, that confirms cause ②.

Step 4: Permanent fix commands by cause

Case ① Disk full / permissions

# Find what is eating the space (old logs, dump.rdb backups, etc.)
du -sh "$RDB_DIR"/* 2>/dev/null | sort -rh | head
# After cleaning unneeded logs/backups (or expanding the volume), fix ownership
sudo chown redis:redis "$RDB_DIR"
sudo chmod 755 "$RDB_DIR"
# Verify immediately with a manual save
redis-cli BGSAVE
redis-cli INFO persistence | grep rdb_last_bgsave_status   # confirm ok

Case ② Not enough memory to fork (overcommit)

Redis forks the process on BGSAVE. With overcommit_memory=0, the kernel refuses the fork as "out of memory." Apply immediately and persist it.

# Apply immediately
sudo sysctl vm.overcommit_memory=1
# Persist so it survives reboot
echo 'vm.overcommit_memory=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
# Verify
redis-cli BGSAVE
redis-cli INFO persistence | grep rdb_last_bgsave_status

Case ③ dir path / permission problem

# Point dir at an existing writable path (adjust the example to your environment)
redis-cli CONFIG SET dir /var/lib/redis
sudo chown redis:redis /var/lib/redis
redis-cli BGSAVE
# Persist runtime config into redis.conf (so a restart does not revert it)
redis-cli CONFIG REWRITE

If the mount is read-only (Read-only file system), the correct fix is to move the save path onto a writable volume.

One note from the field: about 80% of the incidents I have seen were case ②. It stays quiet until traffic grows and memory use crosses half of physical RAM, then fork is refused and it blows up "out of nowhere." That is the "it was fine yesterday" mystery. Always set vm.overcommit_memory=1 when you stand up a new Redis.

If you are on containers / k8s

On k8s, ① and ③ often show up as emptyDir or PV capacity exhaustion, or file permissions from an initContainer (fsGroup not set). Run the same diagnostics via kubectl exec, but the real fix is raising PVC size and setting securityContext.fsGroup. On managed Redis such as ElastiCache, you cannot touch stop-writes-on-bgsave-error or overcommit, so look at parameter groups, node type, and storage metrics in the console rather than chasing MISCONF itself.

Step 5: Recurrence checklist + restore stop-writes

Once the root cause is fixed, you must turn the safety switch back on from step 1. That way the next save failure pages you immediately instead of silently losing data.

redis-cli CONFIG SET stop-writes-on-bgsave-error yes
redis-cli CONFIG REWRITE   # keep yes across restarts

• Final check: rdb_last_bgsave_status:ok
• vm.overcommit_memory=1 as a default (persisted in /etc/sysctl.conf)
• Disk usage alerts at 80% (root volume and the RDB dir volume separately)
• Health checks on rdb_last_bgsave_status / aof_last_bgrewrite_status
• Periodic check that dir is owned by redis:redis and the mount is writable
• Confirm stop-writes-on-bgsave-error yes is restored ← skip this line and the next incident is the worst one

Reference: official docs

The primary source for the behavior, settings, and errors in this post is the official documentation below. Check version-specific options and exact behavior there.

• Redis official documentation

FAQ

Q. Can I just leave stop-writes-on-bgsave-error no forever? A. Not recommended. You would be silently ignoring save failures and leaving restart-time data loss on the table. Use it only as a temporary workaround, then flip it back to yes after the cause is fixed. If this Redis is a pure cache with no RDB and you accept loss, it is cleaner to disable saving itself (save "").

Q. Disk has plenty of space and permissions look fine, but MISCONF keeps coming back. A. Almost certainly fork memory (cause ②). Confirm fork: Cannot allocate memory in journalctl and set vm.overcommit_memory=1. This often hits when Redis data grows past half of physical RAM.

Q. Does this runbook work on ElastiCache? A. Not as-is — you cannot use CONFIG SET or sysctl. On managed Redis, respond with storage/memory metrics, parameter groups, and node scale-up. MISCONF itself is uncommon there.