Node.js cannot reach PostgreSQL: connect ETIMEDOUT in production
Error: connect ETIMEDOUT 10.0.12.34:5432Short 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.
Fix it fast
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 54322Match what you see, then jump to its fix
- 1
nc 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
The default outbound rule was removed from the app's security groupThe app's own security group blocks outbound trafficFix - 3
After the firewall is open, the error becomes ECONNREFUSED instead of ETIMEDOUTPostgreSQL listens only on localhostFix
- 1
What does the error look like?
Error: connect ETIMEDOUT 10.0.12.34:5432at 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 54322Fix
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 5432Confirmed by docs.aws.amazon.com
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 54322Fix
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 5432Confirmed by docs.aws.amazon.com
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 5432Confirmed by postgresql.org
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix