Redis: "Connection Refused" on 6379 — Find the Refusing Layer

Nothing accepted the TCP connection: Redis down, bound to a different interface, or firewalled. Each layer has a one-command check — and the protected-mode/allowlist variants fail differently (auth, not refused), which narrows it fast.

What you'll see

Root causes

Redis isn't running (or crashed on boot)

systemctl status redis-server plus the log. Common crash cause: maxmemory policies or a bad config edit; the service then fails at every boot until the config is fixed.

bind + protected-mode configuration

Default bind 127.0.0.1 refuses external interfaces. Setting bind 0.0.0.0 without also handling protected-mode (no password + non-loopback = refuse) leaves a half-open config that still refuses.

Firewall/security group blocking 6379

Cloud security groups, ufw, or the container network. nc -zv from the app host distinguishes network-block (timeout) from actively-refused (nothing listening there).

Fix it

  1. Locally: is Redis up and where is it listening?
    systemctl status redis-server --no-pager ; ss -ltnp | grep 6379   # 127.0.0.1:6379 only = bind config
  2. From the app host: test reachability
    nc -zv -w 3 <redis-host> 6379   # refused = not listening/filtered-refused; timeout = firewall drop
  3. Open it deliberately (bind + auth, never just 0.0.0.0)
    # redis.conf: bind 0.0.0.0 protected-mode no requirepass <strong-pass>  — plus a firewall rule scoped to the app hosts
  4. Container networks: use the service name, not localhost
    # compose: redis://redis:6379 (service DNS) — localhost inside the app container is the app container, never the redis one

Field note

The localhost-in-containers trap deserves its own headline: every container has its own network namespace, so 127.0.0.1:6379 from the app container refuses even when redis runs one hop away. An internet-exposed Redis without auth is typically compromised within minutes: opening the bind without requirepass is not a shortcut, it's an incident.

Common questions

Why does redis-cli work on the server but the app can't connect?

redis-cli defaults to the socket/loopback where Redis listens; your app connects over the network where bind/firewall rules apply. Same daemon, different path, different gatekeepers.

Is protected-mode the same as a password?

No: protected-mode refuses non-loopback connections when no auth is configured. It's a safety net against accidental exposure — the real access control is requirepass/ACL plus the firewall.

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.