The Redis LOADING error means the Redis server is busy populating its in-memory dataset from disk and cannot serve client requests until this is complete.
The most common culprit is Redis restarting and needing to load its RDB snapshot or AOF log file.
Cause 1: RDB file corruption or incomplete write.
Diagnosis: Check redis-cli --rdb-check-dump <path_to_rdb_file>. If it reports errors, the file is bad.
Fix: Delete the corrupted RDB file (e.g., rm dump.rdb) and restart Redis. Redis will start with an empty dataset. If you have a backup, restore it.
Why it works: Redis cannot load a damaged file, so removing it allows it to start fresh.
Cause 2: AOF file corruption or syntax error.
Diagnosis: Use redis-cli --aof-check <path_to_aof_file>. If it reports errors, the file is bad.
Fix: If the AOF file is corrupted, you can try to rebuild it from the last valid RDB snapshot. Stop Redis, rename the corrupted AOF file (e.g., mv appendonly.aof appendonly.aof.bak), start Redis with redis-cli --aof-no-appendfsync no (temporarily disabling fsync for faster startup), and then issue a BGREWRITEAOF command. This will create a new, clean AOF file.
Why it works: Rebuilding the AOF from a known good state (RDB) bypasses the corrupted entries.
Cause 3: Insufficient memory to load the dataset.
Diagnosis: Run redis-cli INFO memory. Look at used_memory_rss and maxmemory. If used_memory_rss is close to or exceeds maxmemory, Redis might be struggling to load. Also, check system dmesg for OOM killer messages.
Fix: Increase Redis’s maxmemory configuration or, more critically, ensure the server has enough physical RAM. If increasing maxmemory, set it to a value slightly less than available RAM. Example: maxmemory 10gb.
Why it works: Redis needs sufficient RAM to hold the entire dataset. If it’s already near its limit, loading a large dataset can fail.
Cause 4: Redis process killed by the OOM killer.
Diagnosis: Check system logs for Out-Of-Memory killer events (sudo dmesg | grep -i oom). This often happens during large data loads or high memory usage.
Fix: Increase server RAM, reduce Redis maxmemory, or optimize your application to use less memory. If you must keep the current memory footprint, consider setting vm.overcommit_memory = 1 in /etc/sysctl.conf and applying it with sysctl -p.
Why it works: This sysctl setting tells the kernel to always allow memory allocations, preventing the OOM killer from terminating Redis, but it can lead to actual OOM situations if memory is truly exhausted. Use with caution.
Cause 5: Disk I/O issues during loading.
Diagnosis: Monitor disk I/O performance during startup using tools like iostat -xm 5. High %util or await times on the disk where RDB/AOF files reside indicate a bottleneck.
Fix: Move RDB/AOF files to a faster disk (e.g., SSD), ensure the disk isn’t saturated by other processes, or optimize Redis persistence settings (e.g., adjust appendfsync to everysec).
Why it works: Slow disk I/O directly translates to slow data loading, prolonging the LOADING state and potentially causing timeouts.
Cause 6: Extremely large dataset and slow disk.
Diagnosis: Check the size of your RDB file (ls -lh dump.rdb) or AOF file. If it’s tens or hundreds of gigabytes, loading will naturally take a long time, especially on slower storage.
Fix: If possible, use RDB snapshots and disable AOF for faster restarts. For very large datasets, consider Redis Cluster or sharding to distribute data, or use a faster storage medium. If using RDB, ensure save configurations are appropriate to minimize downtime between restarts.
Why it works: The time to load is directly proportional to the size of the data file and the speed of the underlying storage.
Cause 7: Incorrect file permissions for RDB/AOF.
Diagnosis: Verify that the user running the Redis process has read permissions for the RDB/AOF file and write permissions for the directory. Use ls -l <path_to_rdb_or_aof_file> and ls -ld <directory_of_rdb_or_aof_file>.
Fix: Adjust permissions using chmod and chown. For example, sudo chown redis:redis /var/lib/redis/dump.rdb and sudo chmod 644 /var/lib/redis/dump.rdb.
Why it works: Redis cannot access or read the data files if the operating system’s permissions prevent it.
After resolving the loading issue, the next error you might encounter is a WRITE error if your persistence settings are too aggressive and block the main thread.