Redis 'Connection Refused': Complete Troubleshooting Guide (Connection Pool, Timeout, Too Many Connections)

Understanding Redis Connection Errors

Redis is a single-threaded, event-loop-driven server. Almost every production incident traces back to one of six failure modes: the process isn't running, the network path is blocked, the server hit its connection ceiling, authentication is misconfigured, a slow command is monopolizing the event loop, or replication has fallen behind. Each mode produces a distinctive error message.

Exact Error Messages You Will See

Error: connect ECONNREFUSED 127.0.0.1:6379          # Node.js / ioredis
redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.  # Python redis-py
ERR max number of clients reached                    # Redis server log
NOAUTH Authentication required.                     # Missing password
WRONGPASS invalid username-password pair             # Wrong credentials (Redis 6+)
READONLY You can't write against a read only replica # Writing to replica
BUSY Redis is busy running a script                  # Long-running Lua

Step 1: Confirm Redis Is Running

The most common cause of Connection refused is that the Redis process stopped — OOM killer, systemd restart policy, or a failed RDB/AOF flush.

# Check process status
systemctl status redis-server   # Debian/Ubuntu
systemctl status redis          # RHEL/CentOS

# Quick connectivity test
redis-cli -h 127.0.0.1 -p 6379 ping
# Expected: PONG
# Got: Could not connect to Redis at 127.0.0.1:6379: Connection refused

# Confirm socket / port is open
ss -tlnp | grep 6379
# If empty: Redis is not listening

If the service is stopped, check /var/log/redis/redis-server.log before restarting:

tail -100 /var/log/redis/redis-server.log | grep -E 'WARN|ERR|FATAL'

Common log entries that explain a crash:

• # Can't save in background: fork: Cannot allocate memory — OOM, enable vm.overcommit_memory = 1
• # Failed opening .rdb for saving: Permission denied — data directory ownership issue
• # Creating Server TCP listening socket 0.0.0.0:6379: bind: Address already in use — port conflict

Step 2: Verify Bind Address and Network Path

By default, Redis 3.2+ binds to 127.0.0.1 only. Remote connections will be refused even if the process is running.

# Check what address Redis is bound to
grep '^bind' /etc/redis/redis.conf
# Default: bind 127.0.0.1 -::1

# Test from a remote host
nc -zv <redis-host> 6379
telnet <redis-host> 6379

# Check firewall (iptables)
iptables -L INPUT -n | grep 6379

# Check firewall (nftables / ufw)
ufw status | grep 6379
nft list ruleset | grep 6379

To allow remote connections safely:

# In redis.conf — bind to specific interface, NOT 0.0.0.0 without a firewall
bind 127.0.0.1 10.0.1.5

# Apply without restart (Redis 6.2+)
redis-cli CONFIG SET bind-source-addr ""  # not for bind directive — requires restart
sudo systemctl reload redis-server

Always pair a non-localhost bind with a firewall rule and requirepass / ACLs.

Step 3: Diagnose and Fix Connection Limits

Too Many Connections / Pool Exhausted

ERR max number of clients reached

Redis has a hard maxclients limit (default: 10000). Connection pools in your application layer are a separate concern.

# Current connection count
redis-cli INFO clients | grep connected_clients
# connected_clients:9987  <-- approaching limit

# See which clients are connected
redis-cli CLIENT LIST

# Check maxclients setting
redis-cli CONFIG GET maxclients

# Raise the limit at runtime (no restart needed)
redis-cli CONFIG SET maxclients 20000

# Persist to redis.conf
echo 'maxclients 20000' >> /etc/redis/redis.conf

# Check OS file descriptor limit (must be > maxclients)
ulimit -n
# If too low:
ulimit -n 65535
# Persist: add to /etc/security/limits.conf
# redis soft nofile 65535
# redis hard nofile 65535

Application-Level Pool Exhaustion

If connected_clients is well below maxclients but your app throws pool errors, the pool is undersized or connections are leaking.

Python (redis-py):

import redis

pool = redis.ConnectionPool(
    host='localhost',
    port=6379,
    max_connections=50,      # tune to your concurrency
    socket_timeout=5,
    socket_connect_timeout=2,
    retry_on_timeout=True
)
client = redis.Redis(connection_pool=pool)

Node.js (ioredis):

const Redis = require('ioredis');
const client = new Redis({
  host: 'localhost',
  port: 6379,
  maxRetriesPerRequest: 3,
  connectTimeout: 2000,
  commandTimeout: 5000,
  lazyConnect: false,
  family: 4
});

Step 4: Diagnose Timeouts and Slow Queries

A redis timeout error means a command took longer than the client's configured timeout. The usual culprit is a slow command blocking the event loop.

# Enable slow log (commands taking > 10ms)
redis-cli CONFIG SET slowlog-log-slower-than 10000   # microseconds
redis-cli CONFIG SET slowlog-max-len 256

# Retrieve the slow log
redis-cli SLOWLOG GET 25
# Output: ID, timestamp, execution time (µs), command + args

# Check instantaneous latency
redis-cli --latency -h localhost -p 6379

# Intrinsic latency (baseline OS noise)
redis-cli --intrinsic-latency 30

# Monitor live commands (use sparingly in prod — impacts performance)
redis-cli MONITOR | head -50

Dangerous commands to find and replace:

# Find all KEYS calls in application code
grep -r 'KEYS \*' ./src --include='*.py' --include='*.js' --include='*.go'

# Use SCAN instead in a script
redis-cli --scan --pattern 'session:*' | wc -l

Step 5: Fix Authentication Errors

Redis 6 introduced ACL-based multi-user authentication. The old requirepass still works but is treated as setting the password for the default user.

# Test authentication
redis-cli -h localhost -p 6379 -a 'yourpassword' ping

# If using ACLs (Redis 6+)
redis-cli ACL LIST
redis-cli ACL WHOAMI

# Add a new user with specific permissions
redis-cli ACL SETUSER appuser on >strongpassword ~* &* +@all

# Persist ACLs to file (recommended over requirepass for Redis 6+)
# In redis.conf:
# aclfile /etc/redis/users.acl
redis-cli ACL SAVE

# Test new user
redis-cli -u redis://appuser:strongpassword@localhost:6379 ping

Step 6: Diagnose and Fix Replication Lag

Replication lag causes stale reads on replicas and can manifest as data loss during failover.

# On the primary
redis-cli INFO replication
# Look for:
# role:master
# connected_slaves:2
# slave0:ip=10.0.1.10,port=6379,state=online,offset=12345678,lag=0
# repl_backlog_size:1048576

# On the replica
redis-cli INFO replication
# Look for:
# role:slave
# master_link_status:up
# master_last_io_seconds_ago:1
# master_sync_in_progress:0
# slave_repl_offset:12345670
# slave_priority:100
# slave_read_only:1

# Calculate lag in bytes
redis-cli -h primary INFO replication | grep master_repl_offset
redis-cli -h replica INFO replication | grep slave_repl_offset

# Increase replication backlog for high-throughput primaries
redis-cli CONFIG SET repl-backlog-size 67108864  # 64MB

# Increase timeout before replica marks primary as down
redis-cli CONFIG SET repl-timeout 120

If replica shows master_link_status:down:

# Check replica log
tail -50 /var/log/redis/redis-server.log | grep -i repl
# MASTER <-> REPLICA sync started
# Error condition on socket for SYNC: Connection timed out
# Reconnecting to MASTER <primary-ip>:6379 after failure

# Force resync from replica
redis-cli REPLICAOF NO ONE   # demote to standalone
redis-cli REPLICAOF <primary-ip> 6379  # re-attach

Step 7: Validate Redis Deadlock / Blocked Clients

# Check for blocked clients (waiting on BLPOP, BRPOP, WAIT)
redis-cli INFO clients | grep blocked_clients

# See which commands are blocking
redis-cli CLIENT LIST | grep flags=b

# Kill a specific blocked client
redis-cli CLIENT KILL ID <client-id>

# Check for Lua script timeouts (BUSY state)
redis-cli DEBUG SLEEP 0  # no-op to test responsiveness
# If this hangs: a Lua script is running
redis-cli SCRIPT KILL  # kills the running script (if not in write)

Production Checklist

• Enable hz 20 in redis.conf for more frequent background task cycles under high load
• Set tcp-keepalive 300 to detect dead connections
• Configure timeout 0 carefully — idle client connections consume memory
• Use maxmemory-policy allkeys-lru to prevent OOM on cache workloads
• Deploy Redis with Sentinel or Cluster for HA; never rely on a single instance in production
• Always set save "" to disable RDB if using Redis purely as a cache (reduces fork latency)