ioredis cannot connect to an ElastiCache endpoint and times out
[ioredis] Unhandled error event: Error: connect ETIMEDOUTShort 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.
Fix it fast
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 63792Match what you see, then jump to its fix
- 1
nc hangs from your laptop or from a server in another network.The app runs outside the cache's VPCFix - 2
The app is in the right VPC and nc still hangs.The security group does not allow port 6379Fix - 3
The TCP test succeeds, but ioredis still fails to connect.In-transit encryption is on and the client connects without TLSFix - 4
The message says Unhandled error event, and nothing in your code handles it.There is no error listener, so the real cause is only loggedFix
- 1
What does the error look like?
[ioredis] Unhandled error event: Error: connect ETIMEDOUTError: 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.js2Fix
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 VPC3Verify
nc succeeds from the machine that runs the app.
nc -vz my-cache.abc123.use1.cache.amazonaws.com 6379Confirmed by docs.aws.amazon.com
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 rules2Fix
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 group3Verify
Retry the TCP test, then start the app.
nc -vz my-cache.abc123.use1.cache.amazonaws.com 6379Confirmed by docs.aws.amazon.com
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 PONGConfirmed by docs.aws.amazon.com
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.jsConfirmed by raw.githubusercontent.com
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
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 fixBack end
Node.js cannot reach Redis: ECONNREFUSED on port 6379
Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED
ECONNREFUSED on 6379 means no Redis server accepted the connection at the address the client used.
4 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
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fix