n8n Redis connection refused error A54? ECONNREFUSED 127.0.0.1:6379 fix

Step by Step Guide to solve n8n Redis Connection Refused Error

 

Who this is for: Developers and DevOps engineers running n8n in Docker who need a reliable Redis backend. For a complete overview of Redis usage, errors, performance tuning, and scaling in n8n, check out our detailed guide on Redis for n8n Workflows.

---

Quick Diagnosis

1. Confirm Redis is alive – docker exec redis redis-cli ping → should return PONG.
2. Validate host / port – n8n must use the exact address (e.g., REDIS_HOST=redis, REDIS_PORT=6379).
3. Test network reachability – docker exec n8n nc -zv redis 6379.
4. Resolve the most common cause (see the table below).
5. Restart the stack – docker compose restart n8n redis.

Result: n8n connects to Redis without the “connection refused” error.

---

1. Core Failure Points

Failure point	Symptom in n8n logs	Quick test
Redis not running	Error: connect ECONNREFUSED	docker ps -f name=redis
Wrong host/port	Same as above	docker exec n8n env | grep REDIS
Network isolation	Same as above	docker network inspect <net>
Bind address / protected‑mode	Same as above	docker exec redis cat /data/redis.conf | grep -E ‘bind|protected-mode’
Firewall / SG block	Same as above	iptables -L -n | grep 6379
TLS mismatch	Error: TLS handshake failed	Verify REDIS_TLS flag
Resource exhaustion	ECONNREFUSED after retries	docker exec redis redis-cli INFO memory

EEFA note: Never expose Redis directly to the internet. Keep it on an internal Docker network or VPC‑private subnet and leave protected-mode enabled unless you have a restrictive firewall. When Redis issues break your n8n workflows, follow the steps in our n8n Redis guide to restore smooth operations.

---

2. Step‑by‑Step Diagnosis

2.1 Verify Redis is alive

# Ping Redis from its own container
docker exec redis redis-cli ping

Expected output: PONG.
If the container isn’t running, start it:

docker compose up -d redis

2.2 Check n8n’s Redis configuration

n8n reads connection details from environment variables. List them inside the n8n container:

docker exec n8n env | grep REDIS

Typical variables:

Variable	Default	Meaning
REDIS_HOST	localhost	Hostname or Docker service name
REDIS_PORT	6379	TCP port
REDIS_PASSWORD	(empty)	AUTH password
REDIS_TLS	false	Set true for TLS

If REDIS_HOST is 127.0.0.1 while Redis runs in a separate container, change it to the service name (redis).

2.3 Test TCP reachability from n8n

# Install netcat (if not present) and test the port
docker exec n8n sh -c "apk add --no-cache netcat-openbsd && nc -zv redis 6379"

Success: Connection to redis 6379 port [tcp/*] succeeded!
Failure: Indicates a networking or firewall issue.

2.4 Align Docker networks

A single‑network Compose file eliminates most connectivity problems.

Compose snippet – services (first 4 lines):

services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    networks: [n8n-net]

Compose snippet – n8n service (next 5 lines):

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on: [redis]
    networks: [n8n-net]

Compose snippet – network definition (final 3 lines):

networks:
  n8n-net:
    driver: bridge

If you already have separate networks, attach both containers to the same one:

docker network connect n8n-net redis
docker network connect n8n-net n8n

2.5 Inspect Redis bind address & protected mode

docker exec redis cat /data/redis.conf | grep -E 'bind|protected-mode'

– Production‑ready: bind 0.0.0.0 and protected-mode no *only* when the Docker network is fully isolated.
– Common mistake: bind 127.0.0.1 blocks external containers.

Fix via Compose override (4‑line command):

redis:
  command: ["redis-server", "--bind", "0.0.0.0", "--protected-mode", "no"]

EEFA warning: Disabling protected mode opens Redis to any host that can reach the port. Ensure the bridge network is private and never expose port 6379 on the host.

2.6 Resolve TLS mismatches

If REDIS_TLS=true in n8n but Redis runs plain, either disable TLS in n8n or enable it in Redis. Confused by Redis command errors in n8n? Our n8n Redis guide has all the fixes you need.

Option A – disable TLS in n8n (2 lines):

environment:
  - REDIS_TLS=false

Option B – enable TLS in Redis (5‑line command):

redis:
  image: redis:7-alpine
  command: [
    "redis-server",
    "--tls-port", "6379",
    "--port", "0",
    "--tls-cert-file", "/certs/redis.crt",
    "--tls-key-file", "/certs/redis.key",
    "--tls-ca-cert-file", "/certs/ca.crt"
  ]
  volumes: ["./certs:/certs:ro"]

2.7 Verify host‑level firewall or cloud SG

On the Docker host, list rules affecting port 6379:

sudo iptables -L INPUT -v -n | grep 6379

If a DROP rule exists, allow traffic on the Docker bridge:

sudo iptables -I INPUT -i docker0 -p tcp --dport 6379 -j ACCEPT

For cloud VMs, ensure the security group permits inbound 6379 **only** from the instance’s private IP range.

---

3. Full‑Resolution Checklist

• Redis container is running (docker ps).
• redis-cli ping inside Redis returns PONG.
• n8n env vars point to the correct service name (REDIS_HOST=redis).
• Network test (nc -zv redis 6379) from n8n succeeds.
• Redis bind is 0.0.0.0 or the Docker network restricts access; protected-mode set appropriately.
• TLS settings (REDIS_TLS) match Redis’s configuration.
• Host firewall / cloud SG allows traffic on 6379 only from trusted sources.
• Restart both containers: docker compose restart redis n8n.

---

4. Real‑World Production Tips (EEFA)

Situation	Recommended Fix
Scaling Redis for multiple n8n workers	Deploy Redis Sentinel or Cluster and set REDIS_SENTINEL_HOSTS in n8n.
High‑availability requirement	Place Redis behind a private load balancer, keep REDIS_TLS=true, and store certs in a secret manager.
Secret management	Use Docker secrets or orchestrator‑provided env vars; never hard‑code passwords.
Observability	Enable Redis slowlog and ship logs to a central system (e.g., Loki) to catch intermittent spikes.
Prevent resource‑exhaustion	Configure maxmemory and maxclients in redis.conf to avoid silent refusals under load.

---

5. Next Steps if Problems Persist

1. Inspect Redis logs for OOM or maxclients messages: docker logs redis.
2. Check sentinel/cluster endpoints if you moved to a HA setup.
3. Increase maxclients or allocate more memory if the logs show resource limits.
4. Open an issue on the n8n GitHub repo with logs and your docker-compose.yml (redact secrets).

---

Conclusion

The “Redis connection refused” error in n8n almost always stems from one of three areas: the Redis process isn’t reachable, the connection parameters are wrong, or the network/firewall blocks traffic. By confirming Redis is alive, aligning Docker networks, fixing bind/protected‑mode settings, and ensuring TLS and firewall rules match, you restore reliable communication. Following the checklist and production tips keeps your stack resilient and secure in real‑world deployments. Want to log and monitor Redis errors in n8n efficiently? Check our comprehensive n8n Redis guide.