n8n Redis unavailable in queue mode – what happens and how to recover

Who this is for: Developers or DevOps engineers running n8n in production (Docker, Kubernetes, or system‑service) who have enabled Queue Mode and encounter a “Redis unavailable” error. We cover this in detail in the n8n Queue Mode Errors Guide.

---

Quick Diagnosis

Fix “Redis unavailable” in n8n Queue Mode – Ensure Redis is running, reachable, and correctly referenced by the n8n environment variables (QUEUE_BULL_REDIS_HOST, QUEUE_BULL_REDIS_PORT, QUEUE_BULL_REDIS_PASSWORD). Restart n8n after any change.

---

1. Why n8n Shows Redis unavailable ?

If you encounter any n8n queue mode database connection failure resolve them before continuing with the setup.

Symptom	Root Cause	Typical Log Message
Queue mode: Redis unavailable	Redis service stopped or crashed	Error: Redis connection to 127.0.0.1:6379 failed
Error after a deploy	Wrong host/port in env vars	Error: getaddrinfo ENOTFOUND redis.my‑domain.com
Error persists while Redis is up	Network policy (Docker bridge, firewall) blocks traffic	Error: connect ECONNREFUSED 10.0.0.5:6379
TLS handshake failures	Mis‑matched REDIS_TLS settings	Error: TLS handshake timeout

EEFA note – In production, run Redis with persistence (appendonly yes) and enable health‑checks. A silent Redis crash will cascade into lost workflow executions.

---

2. Prerequisites & Tools

If you encounter any n8n queue mode sqlite locking issue resolve them before continuing with the setup.

Tool	Purpose	Install Command
redis-cli	Directly query Redis health	apt-get install redis-tools (Debian)
nc (netcat)	Test TCP connectivity	yum install nc (RHEL)
docker-compose	Manage n8n & Redis containers	pip install docker-compose
curl	Verify HTTP health endpoint (Redis‑Exporter)	Pre‑installed on most Linux

Tip: Keep a copy of the current .env file in version control before editing.

---

3. Step‑by‑Step Restoration Guide

3.1 Confirm Redis Service Status

Check whether Redis is running on the host or inside Docker.

# Systemd‑managed Redis
sudo systemctl status redis

# Docker‑compose
docker compose ps redis

Expected: active (running) or Up with health healthy. If Redis is down, start it:

# Systemd
sudo systemctl start redis

# Docker
docker compose up -d redis

3.2 Test Direct Connectivity

Validate that n8n can reach Redis over the network.

# TCP test (replace vars if needed)
nc -zv ${REDIS_HOST:-127.0.0.1} ${REDIS_PORT:-6379}

# Redis ping
redis-cli -h ${REDIS_HOST:-127.0.0.1} -p ${REDIS_PORT:-6379} ping

Successful output: Connection … succeeded! and PONG. If the ping fails, examine firewall rules, cloud security groups, or Docker network isolation.

3.3 Verify Authentication & TLS

Test the credentials and TLS configuration that n8n will use.

# With password
redis-cli -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD ping

# With TLS (BullMQ respects REDIS_TLS)
redis-cli -h $REDIS_HOST -p $REDIS_PORT --tls \
  --cert /path/to/cert.pem --key /path/to/key.pem ping

EEFA note – Store passwords in a secret manager (AWS Secrets Manager, Vault) for production; avoid plain‑text .env values.

3.4 Align n8n Environment Variables

Variable	Default	Recommended Production Value
QUEUE_MODE	none	bull
QUEUE_BULL_REDIS_HOST	localhost	Redis service name (redis in Docker)
QUEUE_BULL_REDIS_PORT	6379	6379
QUEUE_BULL_REDIS_PASSWORD	(empty)	Secret reference
QUEUE_BULL_REDIS_TLS	false	true if TLS enabled

After editing .env (or Docker secret), reload n8n:

# Docker
docker compose restart n8n

# PM2 (systemd binary)
pm2 restart n8n

3.5 Validate n8n’s Queue Health

Inspect the logs for a successful BullMQ connection.

docker compose logs -f n8n | grep -i "queue"
# Look for: "BullMQ connected to Redis"

Optionally, query the health endpoint (if enabled):

curl http://localhost:5678/health
# JSON should contain "queue": "connected"

If the log still shows “Redis unavailable”, continue with the advanced checklist.

---

4. Advanced Troubleshooting Checklist

• Redis maxmemory exceeded – Run redis-cli INFO memory and verify used_memory ≤ maxmemory. Reduce job payload size or increase memory.
• Eviction policy mismatch – Ensure volatile-lru or allkeys-lru aligns with queue usage.
• Network namespace clash – In Docker, confirm both containers share the same network (docker compose up -d uses the default network).
• Duplicate QUEUE_BULL_REDIS_* variables – Run env | grep QUEUE_BULL_REDIS to detect hidden overrides.
• BullMQ version mismatch – n8n v1.xx ships with BullMQ 4.x; older Redis clients may lack RESP3 support. Upgrade n8n or pin BullMQ version.

EEFA warning – Disabling appendonly or save for performance can cause data loss if Redis crashes while jobs are pending. Keep persistence enabled in production.

---

5. Preventive Measures & Best Practices

Practice	Why It Helps	Implementation
Redis Sentinel	Automatic failover prevents “unavailable” state during node loss	Deploy Sentinel alongside primary Redis, set QUEUE_BULL_REDIS_SENTINEL_HOSTS
Health‑check probes	Docker/K8s can restart failing containers before n8n notices	Add healthcheck in docker-compose.yml using redis-cli ping
Metrics & Alerts	Early detection of latency spikes or memory pressure	Use redis-exporter + Prometheus + Alertmanager
Separate queue Redis	Isolates workflow jobs from cache/session Redis, reducing contention	Spin a dedicated Redis instance for n8n queue mode
Version pinning	Avoids breaking changes from upstream library updates	npm install @nestjs/bull@4.0.0 (if self‑hosting)

 

---

Conclusion

The “Redis unavailable” error in n8n Queue Mode is almost always a connectivity or configuration problem. By:

1. Confirming Redis is up
2. Testing network reachability
3. Validating authentication/TLS
4. Synchronizing n8n’s QUEUE_BULL_REDIS_* variables

you can restore queue processing within minutes and keep automated workflows reliable in production. Implement the preventive practices above to avoid future outages and maintain a resilient workflow execution pipeline.