Maaz Zindani

Loading the index…

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

ioredis cluster client cannot load the slot map from any node

ErrorClusterAllFailedError: Failed to refresh slots cache.

Short answer

This error means ioredis asked every startup node for the cluster slot map and every attempt failed. The error object carries the last node failure in lastNodeError, so print it first. On AWS ElastiCache the usual causes are TLS settings missing from the client, a network path that does not reach the nodes, or a missing password.

  • Applies to ioredis 5, Node.js 22, Amazon ElastiCache for Redis OSS cluster mode
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    ioredis keeps the failure of the last node it tried in lastNodeError. Print it, because the message there (timeout, refused, certificate, auth) tells you which cause below applies.

    const Redis = require("ioredis");
    const cluster = new Redis.Cluster(
      [{ host: "my-cluster.example.cache.amazonaws.com", port: 6379 }]
    );
    cluster.ping().then(console.log).catch((err) => {
      console.error(err.name, err.message);
      console.error(err.lastNodeError);
    });
  2. 2Match what you see, then jump to its fix

    1. 1lastNodeError points at a TLS or certificate failure, or the connection is closed straight after it opensThe cluster has TLS turned on and the client does not use itFix
    2. 2lastNodeError is a connection timeout, and the same host cannot open the port with a plain socketThe app host has no network path to the cluster nodesFix
    3. 3lastNodeError is an authentication error rather than a timeout or a DNS errorThe cluster needs a password and the client sends noneFix
    4. 4lastNodeError names a private address (10.x, 172.x) that times out, although the address you configured is reachableThe cluster hands out node addresses the client cannot reachFix

What does the error look like?

  • ClusterAllFailedError: Failed to refresh slots cache.

Cause 1 of 4

The cluster has TLS turned on and the client does not use it

1Check

Serverless caches always have in-transit encryption on, and a node-based replication group has it when it was created with TransitEncryptionEnabled. A client that connects in plain text to such a cluster cannot load the slot map. The ioredis README adds that ElastiCache with TLS needs its own dnsLookup function, otherwise you can hit invalid-certificate errors.

grep -rn -e tls -e dnsLookup src/

2Fix

Turn on TLS in redisOptions and pass the documented dnsLookup function so the hostname is kept for certificate checking.

const cluster = new Redis.Cluster(
  [{ host: "my-cluster.example.cache.amazonaws.com", port: 6379 }],
  {
    dnsLookup: (address, callback) => callback(null, address),
    redisOptions: { tls: {} },
  }
);

3Verify

Run the ping from the first step again. It should print PONG.

node ping.js

Confirmed by github.com

Did this fix it?

Cause 2 of 4

The app host has no network path to the cluster nodes

1Check

A node-based ElastiCache cluster in a VPC can only be reached from EC2 instances in the same VPC (or a peered one), and the cluster's security group must allow the Redis port. Open a raw TCP connection from the machine that runs the app.

node -e "require('net').connect(6379, 'my-cluster.example.cache.amazonaws.com').on('connect', () => { console.log('open'); process.exit(0) }).on('error', (e) => { console.log(e.message); process.exit(1) })"

2Fix

Run the app inside the same VPC (or peer the VPCs), and add an inbound rule for TCP 6379 on the cluster's security group that allows the app's security group. A laptop on the public internet cannot reach a node-based cluster.

# EC2 console > Security Groups > the cluster's group > Inbound rules
# Type: Custom TCP   Port range: 6379   Source: the app's security group

3Verify

The raw socket check prints open, then the ping from the first step returns PONG.

node ping.js

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 4

The cluster needs a password and the client sends none

1Check

If the cluster uses AUTH, ioredis has to send the password to every node it connects to. The README describes redisOptions as the default options passed to each node connection, so that is where the password goes.

grep -rn "new Redis.Cluster" src/

2Fix

Put the password in redisOptions. If some nodes use a different password, give it in the node list entry for that node, as the README describes.

const cluster = new Redis.Cluster(nodes, {
  redisOptions: {
    password: process.env.REDIS_PASSWORD,
  },
});

3Verify

Run the ping again with the environment variable set.

REDIS_PASSWORD='the-real-password' node ping.js

Confirmed by github.com

Did this fix it?

Cause 4 of 4

The cluster hands out node addresses the client cannot reach

1Check

The README describes clusters hosted in an internal network that can only be reached through a NAT. If the nodes announce internal addresses, ioredis tries those and fails. Run the first-step script and read the host in lastNodeError.

node ping.js

2Fix

Give ioredis a natMap that translates each internal address:port to one the client can reach.

const cluster = new Redis.Cluster(
  [{ host: "203.0.113.73", port: 30001 }],
  {
    natMap: {
      "10.0.1.230:30001": { host: "203.0.113.73", port: 30001 },
      "10.0.1.231:30001": { host: "203.0.113.73", port: 30002 },
    },
  }
);

3Verify

Run the ping again, then a command on a few different keys so several nodes are used.

node ping.js

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep the TLS, password and node list in one shared client factory so every service builds the cluster client the same way.
  • Log err.lastNodeError wherever you handle cluster connection errors; the top-level message never says why.
  • Create ElastiCache and the app in the same VPC and manage the security group rule in your infrastructure code.

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

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

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.