Technology · PRACTICAL GUIDE
Redis says “MISCONF … unable to persist to disk”? Prove the failed RDB boundary before re-enabling writes
Do not treat CONFIG SET stop-writes-on-bgsave-error no as proof of recovery. Capture the client error, runtime RDB path, server log, filesystem and INFO persistence; repair one measured cause, then require a successful BGSAVE, updated snapshot, and representative write.
Redis returns MISCONF when its configured RDB background save has failed and the write-stop safety policy is active. The message explains why writes are blocked; it does not tell you whether the underlying cause is full blocks, exhausted inodes, a read-only mount, directory ownership, or failure to create the background-saving child.
Preserve the evidence before changing policy. Identify the live Redis process and its configured RDB directory, correlate the client error with the matching server log and INFO persistence, repair one measured boundary, then prove a new snapshot completed and a representative write succeeds.
Freeze the error and identify the live RDB target
Save the exact client error, timestamp, Redis endpoint, and the first matching server-log lines. Record INFO server and INFO persistence, then read CONFIG GET dir, CONFIG GET dbfilename, and CONFIG GET stop-writes-on-bgsave-error from the same instance. This prevents diagnosing the wrong container, replica, port, or data directory.
Do not begin by toggling the policy. The current directory and filename define the filesystem that must accept a temporary snapshot and its final rename. In a container, inspect that path and mount from the container namespace or its runtime metadata, not from an unrelated host directory that merely looks similar.
Classify the first failing boundary
Match the server log to a bounded cause. For ENOSPC, run df on the configured directory for free blocks and df -i for inodes. For permission errors, inspect the directory chain, ownership, mode, security labels, and the effective Redis user. For EROFS, confirm the active mount options rather than changing Unix mode bits.
If the log says the background child could not be created or terminated, preserve memory, overcommit, cgroup, and process-limit evidence before tuning. A failed fork boundary is not repaired by freeing a few data-directory blocks, and a read-only mount is not repaired by changing Redis policy.
Repair one measured cause with the smallest reversible change
Free or extend the exact filesystem when blocks or inodes are exhausted; correct the intended data-directory ownership or runtime mount when access is denied; restore the intended writable mount when it is read-only; or address the proven child-process resource boundary. Keep a record of the before and after values.
Avoid moving dir to an arbitrary writable path without verifying persistence, backups, ownership, and restart behavior. Avoid chmod 777, broad privilege changes, destructive key deletion, or a restart used only to clear the visible symptom. Each can hide the original boundary without making the snapshot durable.
Run an RDB exit test before restoring policy
When no conflicting persistence operation is active, run BGSAVE and wait for completion. Re-read INFO persistence and require rdb_last_bgsave_status:ok, no unexpected save still in progress, and a newer last-save time. Inspect the configured directory for the expected RDB file owned by the intended identity.
The temporary-file-to-rename path matters: a command reply alone is not the whole exit test. Correlate the successful server log, INFO fields, snapshot timestamp and size, and—where available—backup or replica monitoring. If any layer disagrees, keep the incident open.
Restore writes deliberately and retain rollback evidence
If the safety policy was temporarily disabled during a controlled emergency, restore the intended value only after persistence is proven, and verify it with CONFIG GET. Perform one non-destructive representative write to a test key in an approved namespace, read it back, and remove it according to local procedure.
Record the client error, log cause, active directory and mount, before-and-after measurements, BGSAVE result, INFO persistence fields, RDB artifact, policy value, and application check. If you cannot prove which boundary failed or cannot produce a successful snapshot, escalate rather than declaring recovery.
