How to Fix Redis Connection Errors in Frappe / ERPNext

🔍 Understanding Redis in Frappe

Frappe uses three Redis instances, each serving a distinct purpose:

When any of these services are stopped or unreachable, Frappe throws connection errors during operations such as:

• App installations (e.g., HRMS, Healthcare)
• Background job execution
• Bench start/restart commands
• Login and session handling

⚠️ Common Error Example

Here’s what a typical Redis connection error looks like:

redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:13000. Connection refused.

This means the Frappe process tried to connect to Redis on 127.0.0.1 (localhost) but no Redis instance was listening on that port.

🧩 Step-by-Step Fix

1️⃣ Verify if Redis is Running

Run the following command to check if Redis is active:

ps aux | grep redis

If Redis isn’t listed, it’s not running. Depending on your environment, fix it using the appropriate method below.

🖥️ A. Fix Redis on a Local (Bare-Metal) Frappe Setup

Step 1: Check Supervisor Status

Frappe uses Supervisor to manage Redis and other background services. Run:

sudo supervisorctl status

You should see something like:

frappe-bench-redis:redis-cache               RUNNING
frappe-bench-redis:redis-queue               RUNNING
frappe-bench-redis:redis-socketio            RUNNING

If any show STOPPED or FATAL, restart them:

sudo supervisorctl restart all

Or restart Redis individually:

sudo supervisorctl restart frappe-bench-redis:redis-cache

Step 2: Restart the Bench

bench restart

This restarts all Frappe-related services, including Redis, workers, and SocketIO.

🐳 B. Fix Redis Inside Docker

In a Dockerized Frappe setup, Redis usually runs in separate containers. If you’re using a custom Docker environment and encounter connection errors, follow these steps.

Step 1: Check if Redis Containers Exist

On the host machine:

docker ps | grep redis

If you don’t see any Redis containers (redis-cache, redis-queue, redis-socketio), create them manually.

Step 2: Create Redis Containers

Run:

docker run -d \
  --name redis-cache \
  --network frappe-net \
  -p 13000:6379 \
  redis:6.2

docker run -d \
  --name redis-queue \
  --network frappe-net \
  -p 11000:6379 \
  redis:6.2

docker run -d \
  --name redis-socketio \
  --network frappe-net \
  -p 12000:6379 \
  redis:6.2

Make sure they appear when you run docker ps.

Step 3: Update Frappe Configuration

Inside your app container (usually frappe-python or makeit), edit:

nano ~/frappe-bench/sites/common_site_config.json

Update the Redis settings:

"redis_cache": "redis://redis-cache:6379",
"redis_queue": "redis://redis-queue:6379",
"redis_socketio": "redis://redis-socketio:6379",

Save and exit, then restart the bench:

bench restart

Step 4: Verify Connectivity

From inside the container:

apt update && apt install redis-tools -y
redis-cli -h redis-cache ping
redis-cli -h redis-queue ping
redis-cli -h redis-socketio ping

Expected output:

PONG

If all three respond, Redis is working correctly.

⚙️ Optional: Check Redis Logs

You can inspect the Redis container logs for troubleshooting:

docker logs redis-cache

Or check Redis persistence and memory usage:

redis-cli -h redis-cache info memory

🚀 Final Step: Reinstall or Retry the App

Once Redis is back online and reachable, re-run your original command:

bench --site your_site_name install-app hrms

This should complete without any connection errors.

🧠 Pro Tips

• Always keep Redis containers on the same Docker network as Frappe and MariaDB.

• Avoid using 127.0.0.1 in Docker — use container names instead.

• Monitor Redis performance using:

  redis-cli -h redis-cache monitor

• If you’re using Docker Compose, you can define Redis services in your docker-compose.yml instead of running them manually.

✅ Summary