Maaz Zindani

Loading the index…

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

Node.js cannot reach PostgreSQL: connect ETIMEDOUT in production

ErrorError: connect ETIMEDOUT 10.0.12.34:5432

Short answer

ETIMEDOUT means the other side never answered the connection attempt. A closed port or wrong address is silent, so the cause is almost always the network path: no inbound rule for port 5432, no outbound rule on the app side, or a database that listens only on localhost. Test the port from the app host with nc before changing code.

  • Applies to Node.js 22, PostgreSQL 16, Amazon EC2 security groups, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run a plain TCP test from the machine that runs Node.js, with the same host and port as your connection settings. A timeout here proves the app code is not the problem.

    nc -zv db.example.com 5432
  2. 2Match what you see, then jump to its fix

    1. 1nc hangs and times out, only from the app host, while a client on the database host connects fineThe database security group has no inbound rule for the appFix
    2. 2The default outbound rule was removed from the app's security groupThe app's own security group blocks outbound trafficFix
    3. 3After the firewall is open, the error becomes ECONNREFUSED instead of ETIMEDOUTPostgreSQL listens only on localhostFix

What does the error look like?

  • Error: connect ETIMEDOUT 10.0.12.34:5432
  • at TCPConnectWrap.afterConnect [as oncomplete]

Cause 1 of 3

The database security group has no inbound rule for the app

1Check

A new security group has no inbound rules, so no inbound traffic is allowed until you add one. Rules only allow traffic; there are no deny rules to look for. Open the database security group and look for TCP 5432 with the app as source.

nc -zv db.example.com 5432

2Fix

Add an inbound rule of type TCP, port 5432 (your PostgreSQL port), with the app's security group as the source. Referencing the security group avoids hard-coding IP addresses.

Type: TCP    Port range: 5432    Source: sg-0123456789abcdef0 (the app security group)

3Verify

Repeat the port test and then start the app.

nc -zv db.example.com 5432

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

The app's own security group blocks outbound traffic

1Check

A new security group allows all outbound traffic, but if the outbound rules were removed, no outbound traffic is allowed at all.

nc -zv db.example.com 5432

2Fix

Add an outbound rule for TCP on the database port, with the database security group or its subnet range as destination.

Type: TCP    Port range: 5432    Destination: sg-0fedcba9876543210 (the database security group)

3Verify

Run the port test again from the app host.

nc -zv db.example.com 5432

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

PostgreSQL listens only on localhost

1Check

listen_addresses defaults to localhost, which allows only local loopback connections. Node.js documents ECONNREFUSED as a connection that the target machine actively refused.

sudo -u postgres psql -c "SHOW listen_addresses;"

2Fix

Set listen_addresses to the interface the app uses, or to *, and restart PostgreSQL (the setting only changes at server start). You must still allow the app's user in client authentication.

# postgresql.conf
listen_addresses = '*'

3Verify

Restart PostgreSQL, then run the port test from the app host.

sudo systemctl restart postgresql
nc -zv db.example.com 5432

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Reference security groups instead of IP addresses in database rules.
  • Keep database host and port in environment variables and print them in the start-up log, without the password.
  • Run the nc test from the app host after every network change.
  • Do not open the database port to 0.0.0.0/0; scope the source to the app.

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

Next step

Want this handled for good?

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