Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js cannot reach Redis: ECONNREFUSED on port 6379

ErrorError: connect ECONNREFUSED 127.0.0.1:6379

Short 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.

  • Applies to Node.js 22, node-redis 5, Redis 8, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 6379
  2. 2Match what you see, then jump to its fix

    1. 1redis-cli also prints Could not connect to Redis, and ss shows no listener on 6379Redis is not running on the hostFix
    2. 2Works 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. 3Redis 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. 4The 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

What does the error look like?

  • Error: connect ECONNREFUSED 127.0.0.1:6379
  • Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED
  • Redis 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-server

2Fix

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:8

3Verify

ping returns PONG.

redis-cli ping

Confirmed by nodejs.org

Did this fix it?

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_URL

2Fix

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 ping

Confirmed by docs.docker.com

Did this fix it?

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 redis

2Fix

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 ping

Confirmed by docs.docker.com

Did this fix it?

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

Did this fix it?

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:

Related fixes

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.