Maaz Zindani

Loading the index…

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

ioredis cannot connect to an ElastiCache endpoint and times out

Error[ioredis] Unhandled error event: Error: connect ETIMEDOUT

Short answer

ETIMEDOUT means packets to the cache never got an answer. ElastiCache in a VPC is reachable only from inside that VPC, so check where your Node.js process runs, then the security group's inbound rule for port 6379, then whether in-transit encryption needs tls in the ioredis options.

  • Applies to ioredis (current), Node.js 22, Amazon ElastiCache for Valkey and Redis OSS
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    From the machine that runs Node.js, test the raw TCP path to the endpoint. If this hangs, the problem is the network, not ioredis.

    nc -vz my-cache.abc123.use1.cache.amazonaws.com 6379
  2. 2Match what you see, then jump to its fix

    1. 1nc hangs from your laptop or from a server in another network.The app runs outside the cache's VPCFix
    2. 2The app is in the right VPC and nc still hangs.The security group does not allow port 6379Fix
    3. 3The TCP test succeeds, but ioredis still fails to connect.In-transit encryption is on and the client connects without TLSFix
    4. 4The message says Unhandled error event, and nothing in your code handles it.There is no error listener, so the real cause is only loggedFix

What does the error look like?

  • [ioredis] Unhandled error event: Error: connect ETIMEDOUT
  • Error: connect ETIMEDOUT

Cause 1 of 4

The app runs outside the cache's VPC

1Check

AWS documents that a cluster launched into a VPC can be reached only from an EC2 instance in the same VPC (or a peered one). It has no public IP address.

# AWS console: ElastiCache > your cluster > read its VPC and subnet group, then compare with the VPC of the machine running Node.js

2Fix

Run the app inside the same VPC or a peered one. For development from outside, AWS describes a NAT instance with port forwarding for testing only, and recommends a Site-to-Site VPN or Client VPN for production.

# run the app on an EC2 instance, container or Lambda attached to the cache's VPC

3Verify

nc succeeds from the machine that runs the app.

nc -vz my-cache.abc123.use1.cache.amazonaws.com 6379

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 4

The security group does not allow port 6379

1Check

A security group attached to the cache needs an inbound rule for the cluster's port, 6379 by default for Valkey and Redis OSS, from your app's security group or subnet range.

# AWS console: ElastiCache > your cluster > security groups, then EC2 > Security Groups > Inbound rules

2Fix

Add an inbound TCP rule on 6379 whose source is the app's security group. AWS suggests a security group used only by ElastiCache rather than the default one.

# EC2 > Security Groups > Inbound > Edit > Add rule: Custom TCP, port 6379, source = the app's security group

3Verify

Retry the TCP test, then start the app.

nc -vz my-cache.abc123.use1.cache.amazonaws.com 6379

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 4

In-transit encryption is on and the client connects without TLS

1Check

Serverless caches always have in-transit encryption enabled, and node-based clusters can have it. AWS says the client must support TLS and have it turned on in its configuration.

# AWS console: the cluster's Encryption in transit setting (the TransitEncryptionEnabled parameter)

2Fix

Turn TLS on in ioredis, with the empty tls object or a rediss:// URL.

const Redis = require('ioredis')
const redis = new Redis({
  host: 'my-cache.abc123.use1.cache.amazonaws.com',
  port: 6379,
  tls: {},
})

3Verify

A ping answers PONG.

redis.ping().then(console.log) // prints PONG

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 4 of 4

There is no error listener, so the real cause is only logged

1Check

ioredis emits connection failures as error events, and the reconnect behaviour is set by retryStrategy. Without a listener you only get the log line.

grep -rn "on('error'" src/

2Fix

Attach an error listener, so each failure is logged with its own message, and let retryStrategy decide the delay between retries.

redis.on('error', (err) => console.error('redis error', err.code, err.message))
// retryStrategy receives the attempt number and returns the delay in ms
const redis2 = new Redis({ retryStrategy: (times) => Math.min(times * 200, 2000) })

3Verify

Start the app and read the error code each failure logs.

node app.js

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Test the raw TCP path with nc before blaming the client library.
  • Keep one security group for the cache and allow only the app's group into it.
  • Always attach an error listener to every ioredis instance.
  • Record in your runbook whether in-transit encryption is on, and keep the tls option in step with it.

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.