Victor's room

Overview & Root Cause Summary: The error Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED occurs when a backend application (Node.js, Python, PHP, or Go) attempts to establish a TCP connection with a local Redis server, but the host operating system actively rejects the connection handshake. This occurs because the Redis daemon is inactive, bound exclusively to an alternative network interface, blocking traffic via protected mode, or misrouted inside containerized Docker networks.

Understanding the Root Causes

• Redis Service Daemon Stopped: The background Redis daemon (redis-server) is stopped, crashed due to memory limits, or failed to start automatically after a system reboot.
• Restrictive Interface Binding: In redis.conf, the bind directive is set to an unexpected address or loopback only, preventing access from Docker containers or adjacent host interfaces.
• Protected Mode Restrictions: By default, Redis enables protected-mode yes, which blocks connections from non-loopback addresses if no authentication password (requirepass) is configured.
• Container Localhost Isolation: In Docker environments, configuring an application container to connect to 127.0.0.1:6379 targets the application container itself rather than the separate Redis container or host machine.

Step 1: Quick Fix (Verify and Start the Redis Daemon)

Check the operational status of the Redis service and ensure it is listening on TCP port 6379.

# 1. Check Redis service status on Ubuntu/Debian:
sudo systemctl status redis-server
# (On CentOS/RHEL/Fedora):
# sudo systemctl status redis

# 2. Start and enable Redis on boot if stopped:
sudo systemctl enable --now redis-server
# (On macOS with Homebrew):
# brew services start redis

# 3. Verify that the daemon is listening on port 6379:
sudo ss -tulpn | grep 6379
# Or using lsof:
sudo lsof -i :6379

Step 2: Configure Network Binding & Protected Mode in redis.conf

Adjust the configuration file to allow connections from local containers or network interfaces securely.

# 1. Open the Redis configuration file:
# Ubuntu/Debian: /etc/redis/redis.conf
# CentOS/RHEL:   /etc/redis.conf
sudo nano /etc/redis/redis.conf

# 2. Configure the bind address (allow loopback and local network or 0.0.0.0 for containers):
bind 127.0.0.1 ::1

# If connecting from Docker containers to the host, bind to 0.0.0.0 and set a password:
# bind 0.0.0.0
# requirepass YourStrongAuthPassword123!

# 3. Restart the Redis service to apply changes:
sudo systemctl restart redis-server

Step 3: Resolve Docker Container Networking & Host Routing

Ensure containerized applications use the Docker Compose service DNS name or host gateway rather than container localhost.

# --- In Docker Compose (docker-compose.yml) ---
# WRONG (attempts to connect to the app container itself):
# REDIS_URL=redis://127.0.0.1:6379

# CORRECT: Use the Compose service name:
services:
  app:
    image: my-node-app:latest
    environment:
      - REDIS_HOST=redis_db
      - REDIS_PORT=6379
  redis_db:
    image: redis:alpine
    ports:
      - "6379:6379"

# If connecting from a container to Redis running on the host OS:
# REDIS_HOST=host.docker.internal

Verification & Testing Steps

Test Redis server responsiveness using the native CLI client and network probing utilities.

# 1. Test ping response via redis-cli:
redis-cli ping
# Expected output: PONG

# 2. If password authentication is enabled:
redis-cli -a YourStrongAuthPassword123! ping

# 3. Probe the TCP port with netcat:
nc -zv 127.0.0.1 6379
# Expected output: Connection to 127.0.0.1 6379 port [tcp/*] succeeded!

Summary Comparison Table