Could not connect to Redis at 127.0.0.1:6379: Connection refused

What it means

Your client asked the machine at that address for a connection on that port, and the machine answered that nothing was listening there. Redis never saw the attempt, so passwords, users and TLS haven’t come into it yet. This is a client-side error with no Redis error code, and each client words it differently:

Neighbouring failures that mean something else:

• The name doesn’t resolve: redis-cli on Linux says Name or service not known, Node.js getaddrinfo ENOTFOUND <host>, Inlet Couldn’t find the host “<host>”: <reason>. Fix the host name; a Docker Compose service name like redis only resolves inside that Compose network.
• No answer at all: Connection timed out (Inlet: Operation timed out). Something drops the traffic: a firewall, a cloud security group, or an address nobody has.
• Connected, then refused by Redis: DENIED Redis is running in protected mode… (see below).
• Connected, then dropped: Connection reset by peer, ECONNRESET, or a client that hangs: usually TLS on one side only (see below).

Common causes

1. Redis isn’t running. The service is stopped, the container exited, or the server failed to start (a bad config file, a port already in use).
2. The wrong port. The server listens on another port, or you used the container’s port (6379) instead of the one published on your Mac.
3. A Docker port that isn’t published. docker run redis without -p runs Redis inside the container only; nothing listens on your Mac.
4. Redis listens only on loopback. The redis.conf that ships with Redis has bind 127.0.0.1 -::1, so a server installed from a package accepts connections from its own machine only. From anywhere else, it’s refused.
5. localhost means two addresses. It resolves to ::1 (IPv6) as well as 127.0.0.1, and a client may try either or both. If Redis or a port forward covers IPv4 only, put 127.0.0.1 in your settings instead.

Two more that start as a connection and then fail:

6. Protected mode. With protected-mode yes (the default in Redis itself) and no password for the default user, Redis accepts connections from loopback only and answers everyone else with DENIED. The official Docker images for Redis and Valkey turn protected mode off.
7. TLS on one side only. A plain client talking to a TLS-only port gets its connection reset; a TLS client talking to a plain port waits for a handshake that never comes, until it times out.

How to fix it

Check that something is listening

From your Mac:

nc -vz <host> <port>

Connection to localhost port 16379 [tcp/*] succeeded!
nc: connectx to 127.0.0.1 port 16390 (tcp) failed: Connection refused

On the server itself, redis-cli -p <port> PING should answer PONG (or NOAUTH, which also proves it’s listening). On macOS, lsof -nP -iTCP -sTCP:LISTEN | grep redis lists the ports Redis listens on.

Start Redis

• Homebrew: brew services start redis (brew services list shows its state).
• Linux with systemd: sudo systemctl status redis-server on Debian and Ubuntu (redis on others); the last log lines say why it stopped.
• Docker: docker ps -a shows exited containers; docker logs <container> shows why.

Publish the Docker port

docker run -d --name redis -p 6379:6379 redis:8

docker ps shows a published port with an address and an arrow; a bare 6379/tcp means it isn’t published:

NAMES                 PORTS
inlet-test-redis8-1   0.0.0.0:16379->6379/tcp, [::]:16379->6379/tcp
seo-redis-acl         6379/tcp

From your Mac, connect to localhost and the port on the left of the arrow. See Redis in Docker.

Reach a server that listens on loopback only

The safest way in is an SSH tunnel, which leaves Redis closed to the network:

ssh -N -L 6379:127.0.0.1:6379 <user>@<server>

Then connect to 127.0.0.1:6379 on your Mac. To accept connections from other machines instead, add the server’s private address to bind in redis.conf (bind 127.0.0.1 -::1 10.0.0.5), restart Redis, give it a password or ACL users, and allow the port only from the machines that need it.

Protected mode: set a password

The DENIED message lists several ways out. The right one for a server other machines reach is a password: requirepass <password> in redis.conf, or ACL users. Turning protected mode off (protected-mode no) without a password leaves Redis open to anyone who can reach the port.

Use TLS on both sides, or neither

If the server accepts only TLS, use a rediss:// URL, or --tls with redis-cli (plus --cacert <file> for a private certificate authority). If the port is plain, drop TLS from the client. Hosted Redis services document which ports use TLS.

Reproduce it

Redis 8.10.2 in Docker, redis-cli 8.10.2 inside the container, nothing listening on 6390:

redis-cli -p 6390 PING

Could not connect to Redis at 127.0.0.1:6390: Connection refused

redis-cli exited with status 1. valkey-cli 8.1.10 printed Could not connect to Valkey at 127.0.0.1:6390: Connection refused (as did its redis-cli name). A name that doesn’t resolve, and an address nobody answers (-t 3 for a three-second limit):

Could not connect to Redis at redis.example.invalid:6379: Name or service not known
Could not connect to Redis at 10.255.255.1:6379: Connection timed out

From Node.js 25 on the Mac, ioredis 5.11.1 retried and logged each failure. With localhost, it tried both addresses and printed an empty message:

[ioredis] Unhandled error event: Error: connect ECONNREFUSED 127.0.0.1:16390
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)

[ioredis] Unhandled error event: AggregateError [ECONNREFUSED]: 
    at internalConnectMultiple (node:net:1134:18)
    at afterConnectMultiple (node:net:1715:7)

Python’s own socket module on the Mac raised ConnectionRefusedError(61, 'Connection refused') for the same port; redis-py builds its message from that error, which is where Error 61 comes from (its wording is taken from its source).

The next tests ran on temporary servers. A Redis 8.10.2 server started with --bind 127.0.0.1, reached from another container:

Could not connect to Redis at 192.168.215.2:6379: Connection refused

A Redis 8.10.2 server started with --protected-mode yes and no password, reached from another container (trimmed):

(error) DENIED Redis is running in protected mode because protected mode is enabled and no password is set for the default user. In this mode connections are only accepted from the loopback interface. If you want to connect from external computers to Redis you may adopt one of the following solutions: 1) Just disable protected mode … 4) Set up an authentication password for the default user. NOTE: You only need to do one of the above things in order for the server to start accepting connections from the outside.

Valkey 8.1.10’s begins DENIED Running in protected mode because protected mode is enabled and no password is set for the default user. From inside the same container, PING answered PONG. CONFIG GET protected-mode on servers started from the redis:8 and valkey/valkey:8 images without that option replied no.

TLS on one side only. Plain redis-cli to the TLS-only test server (Redis 8.10.2):

Error: Connection reset by peer

With a password, it printed I/O error twice before that line. The server logged Error accepting a client connection: error:0A00010B:SSL routines::wrong version number. The other way round, redis-cli --tls against a plain server printed nothing and waited until timeout 8 stopped it. ioredis reported Error: read ECONNRESET in the first case and, after its connect timeout (10 seconds by default), Error: connect ETIMEDOUT in the second.

In Inlet

Inlet says Couldn’t connect to <host>:<port>: Connection refused (or Operation timed out), and Couldn’t find the host “<host>”: <reason> for a name that doesn’t resolve. When the server accepts only TLS and the connection doesn’t use it, Inlet says “The server closed the connection while Inlet was signing in. If it accepts only TLS, turn on TLS for this connection.” TLS (rediss://) checks the server’s certificate; if that fails, Inlet says “The server’s certificate couldn’t be verified:” followed by OpenSSL’s reason. For a Redis that listens on loopback only, Inlet can connect through an SSH tunnel using the system ssh, so your ~/.ssh/config and SSH agent work.