Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Redis answers every command with LOADING after a restart

ErrorLOADING Redis is loading the dataset in memory

Short answer

LOADING means the server is up but still reading its RDB or AOF file back into memory, so it refuses most commands until that finishes. Read the loading fields of INFO persistence to see the progress. Wait for loading to reach 0, make clients retry, and keep the dataset small enough that restarts stay short.

  • Applies to Redis 7.4, Redis 8, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the server how far the load has got. If loading is 1, the other fields show bytes loaded and the time left.

    redis-cli INFO persistence | grep -E '^(loading|loading_loaded_perc|loading_eta_seconds)'
  2. 2Match what you see, then jump to its fix

    1. 1loading:1 with loading_loaded_perc below 100A restart is reading a large RDB or AOF fileFix
    2. 2The error appears on a replica right after it was added or reconnectedA replica is loading data from its primaryFix
    3. 3LOADING appears after each deploy or container restart and lasts longer as data growsThe restart brings the dataset back from disk on every deployFix

What does the error look like?

  • LOADING Redis is loading the dataset in memory
  • (error) LOADING Redis is loading the dataset in memory

Cause 1 of 3

A restart is reading a large RDB or AOF file

1Check

After a restart, Redis replays the RDB snapshot (or the AOF) into RAM before it serves normal traffic. The bigger the file, the longer the window. INFO reports the percentage and an estimated time.

redis-cli INFO persistence | grep -E '^loading'

2Fix

Wait for loading to reach 0. In the app, treat LOADING as a temporary error: retry with a short backoff instead of failing the request, and let your health check call PING or read the loading flag before a node gets traffic.

# wait until the server has finished loading
until [ "$(redis-cli INFO persistence | tr -d '\r' | awk -F: '$1=="loading"{print $2}')" = "0" ]; do
  sleep 1
done

3Verify

The loading flag is 0 and a normal command works.

redis-cli INFO persistence | grep '^loading:'
redis-cli PING

Confirmed by redis.io

Did this fix it?

Cause 2 of 3

A replica is loading data from its primary

1Check

A replica receives a full dataset from the primary and loads it. With repl-diskless-load set to swapdb, Redis 7.0 and later can keep serving the old data while it loads, and INFO shows that as async_loading.

redis-cli -h REPLICA_HOST INFO persistence | grep -E '^(loading|async_loading)'

2Fix

Do not send traffic to the replica until loading is 0 again, or read from the primary meanwhile. Check the replica's log for the end of the synchronisation.

redis-cli -h REPLICA_HOST INFO replication

3Verify

loading is 0 on the replica and the link to the primary reports up.

redis-cli -h REPLICA_HOST INFO replication | grep master_link_status

Confirmed by redis.io

Did this fix it?

Cause 3 of 3

The restart brings the dataset back from disk on every deploy

1Check

Compare the size of the snapshot or the append-only files with the time loading takes. Redis keeps the data in memory and uses the files only to restore it, so restore time grows with the dataset.

redis-cli CONFIG GET dir
ls -lh "$(redis-cli CONFIG GET dir | tail -n1)"

2Fix

Stop restarting a big instance for routine deploys. For upgrades use the documented procedure: start a replica of the current instance, let it sync, switch clients to it, then promote it. That keeps a node serving while the new one loads.

# on the new instance
redis-cli REPLICAOF OLD_HOST 6379
# after clients moved
redis-cli REPLICAOF NO ONE

3Verify

Clients keep getting answers during the switch.

redis-cli -h NEW_HOST PING

Confirmed by redis.io

Did this fix it?

How do I stop it coming back?

  • Make your client retry LOADING with a short backoff instead of treating it as a hard failure.
  • Use a readiness check that waits for the loading flag to be 0 before a Redis node is put behind a load balancer.
  • Keep one instance for one purpose, so a cache restart does not wait on a large durable dataset.
  • Upgrade through a replica instead of restarting the only copy.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.