Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Node.js cannot reach MySQL: connect ETIMEDOUT

ErrorError: connect ETIMEDOUT

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

  • Applies to Node.js 22, mysql 2.18 (mysqljs), mysql2 3.x, MySQL 8.4, Amazon RDS for MySQL
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1nc 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. 2The 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. 3The 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. 4The 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

What does the error look like?

  • Error: connect ETIMEDOUT
  • code: '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 rules

2Fix

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 3306

Confirmed by docs.aws.amazon.com

Did this fix it?

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 accessible

2Fix

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

3Verify

Run the port test again and then start the app.

nc -zv your-db-endpoint.example.com 3306

Confirmed by docs.aws.amazon.com

Did this fix it?

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 3306

2Fix

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 3306

Confirmed by dev.mysql.com

Did this fix it?

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

Confirmed by raw.githubusercontent.com

Did this fix it?

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:

Related fixes

Databases

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

Next step

Want this handled for good?

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