Redis Connection Refused (localhost:6379)

Refused means the Redis process isn't accepting connections on the port you're hitting. Walk the standard chain — process, bind, protected-mode, firewall — and it's usually a five-minute fix.

What you'll see

Root causes

Redis isn't running (or crashed)

systemctl status redis-server and redis-cli ping tell you in ten seconds. Crashes often follow OOM kills or a corrupted AOF on restart — check journalctl -u redis-server -n 50.

Bind address or port changed

Default bind 127.0.0.1 (-::1). If you connect remotely, redis.conf must bind your interface — protected-mode also blocks external connections by default.

Docker networking mismatch

localhost:6379 on the host isn't the container's localhost. The port must be published (-p 6379:6379), or the app should join the same docker network and use the service name.

Fix it

  1. Check process and service state
    systemctl status redis-server --no-pager; redis-cli -h 127.0.0.1 -p 6379 ping
  2. Read the startup logs for the crash reason
    journalctl -u redis-server -n 50 --no-pager | tail -20   # look for 'Killed', AOF/RDB load errors, or overcommit warnings
  3. Fix remote access deliberately (never 0.0.0.0 + no auth)
    # /etc/redis/redis.conf: bind <iface-ip> 127.0.0.1 ; protected-mode yes ; requirepass <strong-secret> ; port 6379
  4. Docker: publish the port or use the network
    docker run -d --name redis -p 6379:6379 redis:7   # app containers: use 'redis' as hostname on a shared network

Field note

Redis refuses to start with a 'Memory overcommit must be enabled' warning on some kernels: sysctl vm.overcommit_memory=1 fixes fork() failures during saves. If Redis only dies under memory pressure, it's the host OOM killer — check kernel logs before blaming Redis.

Common questions

Redis runs but my app can't connect from another host. Why?

Default bind is loopback-only and protected-mode blocks external clients. Set bind to include the right interface, keep protected-mode on with a requirepass, then reload: systemctl restart redis-server.

How is Redis connection refused different from a timeout?

Refused = host reachable, nothing listening (process down or bind/port mismatch). Timeout = packets dropped (firewall, wrong host). That distinction cuts your debug time in half.

Related fixes

Ship it right the first time

Our most-documented failures, packaged as ready-to-ship starter kits: Docker, Kubernetes, and Terraform.

Browse the template store →

One-time. Yours to modify. Instant download from the NinjaOps template store.