Redis Connection Refused: Diagnose and Fix in 5 Steps

yazar

Redis Connection Refused: Diagnose and Fix in 5 Steps

Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED 127.0.0.1:6379

Your caching layer is down, your app is throwing errors, and you need to fix it fast.

Here’s the systematic way to diagnose and resolve Redis connection failures.

Step 1: Is Redis Actually Running?

# Check if Redis process exists
ps aux | grep redis

# Check systemd service status
sudo systemctl status redis
sudo systemctl status redis-server  # Ubuntu/Debian

# Check if it's listening on the port
ss -tlnp | grep 6379

If Redis is stopped: 

sudo systemctl start redis-server
sudo systemctl enable redis-server  # Auto-start on boot

Step 2: Test the Connection Directly

# Basic ping test
redis-cli ping
# Expected: PONG

# If using a password (requirepass)
redis-cli -a your_password ping

# If Redis is on a different host
redis-cli -h your-redis-host -p 6379 ping

If redis-cli works but your app can’t connect — the problem is in your app’s connection config, not Redis itself.

Step 3: Check Redis Bind Configuration

A common issue: Redis is running but only accepting connections from localhost. 

# Check current bind config
grep -i "^bind" /etc/redis/redis.conf

Default output: 

bind 127.0.0.1 -::1

This means Redis only accepts connections from 127.0.0.1. If your app is in a Docker container, it can’t reach this address.

Fix for Docker: 

# Option 1: Bind to all interfaces (careful in production)
# In /etc/redis/redis.conf:
bind 0.0.0.0

# Option 2: Use host.docker.internal (Mac/Windows Docker Desktop)
# In your app:
REDIS_HOST=host.docker.internal

# Option 3: Docker Compose (best practice)
# Put Redis and app in the same Docker network, use service name
REDIS_HOST=redis  # the service name in docker-compose.yml

Step 4: Check Redis Memory (Prevent Future Failures)

Redis can crash or refuse writes if it runs out of memory: 

redis-cli info memory | grep -E "used_memory_human|maxmemory_human|maxmemory_policy"

used_memory_human:1.23G
maxmemory_human:1.00G        # Uh oh — used > max
maxmemory_policy:noeviction  # Refuses writes when full

Fix: 

# Set a sensible eviction policy
redis-cli CONFIG SET maxmemory-policy allkeys-lru

# Increase memory limit
redis-cli CONFIG SET maxmemory 2gb

# Persist config changes
redis-cli CONFIG REWRITE

Step 5: Check Firewall Rules

# Is port 6379 open?
sudo ufw status | grep 6379

# If you need external access (be careful)
sudo ufw allow from your-app-server-ip to any port 6379

# Check iptables if not using ufw
sudo iptables -L -n | grep 6379

Security note: Never expose Redis port 6379 to the open internet. Always restrict by IP or use a private network.

Quick Connection Test Script

#!/bin/bash
HOST=${REDIS_HOST:-127.0.0.1}
PORT=${REDIS_PORT:-6379}

echo "Testing Redis at $HOST:$PORT..."

# Test TCP connection
nc -zv $HOST $PORT 2>&1 && echo "TCP: OK" || echo "TCP: FAILED"

# Test Redis response
redis-cli -h $HOST -p $PORT ping && echo "Redis: OK" || echo "Redis: FAILED"

I built ARIA to solve exactly this.
Try it free at step2dev.com — no credit card needed.