Node.js cannot reach MySQL: connect ETIMEDOUT
Error: connect ETIMEDOUTShort answer
ETIMEDOUT on connect means packets to the database port got no answer at all. The database is not down in the way a refused connection would be; something drops the traffic. On Amazon RDS it is almost always a security group rule or a private instance. Test the port with nc, then fix the rule or the address.
Fix it fast
1Find out which cause you have
Test the TCP port from the machine that runs the Node.js app, not from your laptop. If this hangs, the problem is the network, not your code.
nc -zv your-db-endpoint.example.com 33062Match what you see, then jump to its fix
- 1
nc hangs and then fails. The same host works from another network or from a machine inside the VPC.The security group does not allow your app's addressFix - 2
The app runs on your laptop or on another provider, and the instance has Public accessibility set to No.The instance is private but the app is outside the VPCFix - 3
The timeout happens against a self-managed server too, not only RDS.A firewall blocks the database port, or the host or port is wrongFix - 4
The error appears after about the same number of seconds every time, and nc succeeds but is slow.The connect timeout is shorter than a slow network needsFix
- 1
What does the error look like?
Error: connect ETIMEDOUTcode: 'ETIMEDOUT'
Cause 1 of 4
The security group does not allow your app's address
1Check
For RDS, the inbound rules of the security group attached to the instance must allow the app's IP address or security group on the database port. By default an instance allows no access.
# RDS console > your instance > Connectivity & security > VPC security groups > Inbound rules2Fix
Add an inbound rule for the database port (3306 for MySQL) whose source is the app's security group or its IP address range.
# Inbound rule on the security group of the database
Type: MySQL/Aurora Protocol: TCP Port: 3306
Source: the app's security group (or its IP range)3Verify
Repeat the port test from the app host.
nc -zv your-db-endpoint.example.com 3306Confirmed by docs.aws.amazon.com
Cause 2 of 4
The instance is private but the app is outside the VPC
1Check
To connect from outside the VPC the instance needs a public IP address, and the subnets in its subnet group need an internet gateway.
# RDS console > your instance > Connectivity & security > Publicly accessible2Fix
Prefer moving the app into the same VPC (or a peered one). If you must connect from outside, set Public accessibility to Yes and keep the security group limited to known addresses.
# RDS console > Modify > Connectivity > Public accessibility: Yes3Verify
Run the port test again and then start the app.
nc -zv your-db-endpoint.example.com 3306Confirmed by docs.aws.amazon.com
Cause 3 of 4
A firewall blocks the database port, or the host or port is wrong
1Check
Confirm the host and port in your connection config, then check whether a local or network firewall blocks the MySQL port (3306 by default). The MySQL manual lists a blocked port among the causes of lost connections.
grep -rn "host\|port" config/ .env 2>/dev/null
nc -zv 203.0.113.10 33062Fix
Correct the host or port, or open the port for the app's address in the firewall.
# Open TCP 3306 in the firewall for the app server's address only,
# using the firewall tool your host runs (cloud firewall, ufw, firewalld).3Verify
Port test, then a real query from Node.js.
nc -zv 203.0.113.10 3306Confirmed by dev.mysql.com
Cause 4 of 4
The connect timeout is shorter than a slow network needs
1Check
The mysql package waits connectTimeout milliseconds for the first connection (10000 by default); mysql2 documents the same default of 10 seconds.
grep -rn "connectTimeout" src/2Fix
Raise connectTimeout only when the path is known to be slow but working, for example a cross-region link. It does not fix a blocked port.
const pool = mysql.createPool({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
connectTimeout: 20000, // ms
});3Verify
Start the app and confirm the first query returns.
node app.jsConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Keep the database in the same VPC and region as the app.
- Put the app's security group, not its IP address, as the source of the database rule.
- Run a port check (nc -zv) as a step in your deploy checklist.
- Log the host and port the app actually uses at start-up, without the password.
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.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
Node.js cannot reach PostgreSQL: connect ETIMEDOUT in production
at TCPConnectWrap.afterConnect [as oncomplete]
ETIMEDOUT means the other side never answered the connection attempt.
3 causes, each with a fixDatabases
NestJS connects to MySQL at ::1 and is refused
Error: connect ECONNREFUSED ::1:3306
::1 is the IPv6 loopback address.
2 causes, each with a fixDatabases
Node.js MySQL: Cannot enqueue Query after a fatal error
code: 'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR'
This error is a symptom, not the problem.
2 causes, each with a fixDatabases
MySQL says Too many connections to a Node.js app
Too many connections
MySQL refuses new clients once max_connections slots are in use.
3 causes, each with a fixDatabases
Node.js says the MySQL server closed the connection
code: 'PROTOCOL_CONNECTION_LOST'
The error means the MySQL server, or something between it and your app, closed a connection your code still held.
3 causes, each with a fixDatabases
SequelizeUniqueConstraintError: Validation error on insert
Unhandled rejection SequelizeUniqueConstraintError: Validation error
Sequelize sends the insert, MySQL rejects it because a unique column or unique index already holds that value, and Sequelize reports it as SequelizeUniqueConstraintError.
3 causes, each with a fix