Node.js cannot reach Redis: ECONNREFUSED on port 6379
Error: connect ECONNREFUSED 127.0.0.1:6379Short answer
ECONNREFUSED on 6379 means no Redis server accepted the connection at the address the client used. Check that Redis listens there. In Docker, use the service name instead of localhost from another container, and publish the port when connecting from the host. Also attach an error listener to the client.
Fix it fast
1Find out which cause you have
Ask Redis directly, from the same machine or container as the app. A PONG means the server is fine and the problem is the address your code uses.
redis-cli -h 127.0.0.1 -p 6379 ping sudo ss -ltn | grep 63792Match what you see, then jump to its fix
- 1
redis-cli also prints Could not connect to Redis, and ss shows no listener on 6379Redis is not running on the hostFix - 2
Works from your laptop, but fails inside docker compose with 127.0.0.1:6379The app runs in a container and Redis is in another oneFix - 3
Redis container is up, redis-cli inside it answers PONG, but the host cannot connectThe app runs on the host but the container port is not publishedFix - 4
The process crashes or hangs with the connection error and no readable message, on node-redis 4 or laterThe client was never given a way to report or connectFix
- 1
What does the error look like?
Error: connect ECONNREFUSED 127.0.0.1:6379Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSEDRedis Client Error
Cause 1 of 4
Redis is not running on the host
1Check
ECONNREFUSED means the target refused the connection, which typically means no service is active at that address.
sudo systemctl status redis-server2Fix
Start Redis and enable it at boot. For a quick local server you can run it in Docker and publish the port.
sudo systemctl enable --now redis-server
# or
docker run -d --name redis -p 6379:6379 redis:83Verify
ping returns PONG.
redis-cli pingConfirmed by nodejs.org
Cause 2 of 4
The app runs in a container and Redis is in another one
1Check
Inside the app container, 127.0.0.1 is that container. Compose services reach each other by service name on the container port.
docker compose ps
docker compose exec app printenv REDIS_URL2Fix
Point the client at the service name.
import { createClient } from 'redis';
const client = createClient({ url: 'redis://redis:6379' });3Verify
The client logs a ready state and a test command works.
docker compose exec redis redis-cli pingConfirmed by docs.docker.com
Cause 3 of 4
The app runs on the host but the container port is not published
1Check
A container port is reachable from outside the Docker network only if it is published as HOST_PORT:CONTAINER_PORT.
docker port redis2Fix
Add a ports entry that maps a host port to 6379, and connect to that host port.
services:
redis:
image: redis:8
ports:
- "6379:6379"3Verify
The host sees the listener.
docker compose up -d
redis-cli -p 6379 pingConfirmed by docs.docker.com
Cause 4 of 4
The client was never given a way to report or connect
1Check
node-redis needs an explicit connect call and an error listener; without the listener a network error is thrown instead of logged.
grep -rn "createClient\|\.connect()\|on('error'" --include=*.js .2Fix
Create the client once, register the error listener, and await connect before using it.
const client = createClient({ url: process.env.REDIS_URL });
client.on('error', (err) => console.error('Redis client error', err));
await client.connect();3Verify
A set and get round trip returns the value.
await client.set('probe', '1');
console.log(await client.get('probe'));Confirmed by redis.io
How do I stop it coming back?
- Read the Redis URL from an environment variable; use the service name in Compose and 127.0.0.1 on a laptop.
- Always register client.on('error') and log it.
- Add a Redis healthcheck in Compose and make the app wait for it.
- Keep Redis closed to the internet; publish the port only on 127.0.0.1 when you must reach it from the host.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
Node.js cannot connect to MongoDB: ECONNREFUSED on port 27017
MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017
ECONNREFUSED means nothing accepted the connection at that address and port.
4 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack end
A Docker build or container says npm: not found
npm: command not found
A container only has the programs its image holds.
3 causes, each with a fixBack end
ECS task stops with exec format error on start
exec /usr/local/bin/docker-entrypoint.sh: exec format error
The container's binary was built for another CPU than the task runs on.
2 causes, each with a fixBack end
req.session is undefined in an Express route
TypeError: Cannot set properties of undefined (setting 'user')
express-session only attaches req.session when its middleware runs first and can reach its store.
3 causes, each with a fixBack end
ioredis cluster client cannot load the slot map from any node
ClusterAllFailedError: Failed to refresh slots cache.
This error means ioredis asked every startup node for the cluster slot map and every attempt failed.
4 causes, each with a fix