Node.js fails with connect ETIMEDOUT while the same URL opens in a browser
Error: connect ETIMEDOUT 203.0.113.10:443Short answer
ETIMEDOUT means the other side did not answer in time. If a browser works from the same machine, the browser may be using a proxy that Node.js ignores by default, or Node.js tries an IPv6 address that does not route and gives up. Enable env-proxy support, or fix the IPv6 route or the attempt timeout.
Fix it fast
1Find out which cause you have
Test the address from the same machine, forcing IPv4, then IPv6. The result shows which cause applies.
curl -4 -sS -o /dev/null -w "%{http_code}\n" https://example.com curl -6 -sS -o /dev/null -w "%{http_code}\n" https://example.com env | grep -i proxy2Match what you see, then jump to its fix
- 1
env | grep -i proxy shows HTTP_PROXY or HTTPS_PROXY values (or the browser is set to a proxy), and Node.js times out on every external hostThe network requires a proxy and Node.js does not use oneFix - 2
curl -4 works and curl -6 hangs or failsThe host has an IPv6 address that does not route, and the attempt window is shortFix
- 1
What does the error look like?
Error: connect ETIMEDOUT 203.0.113.10:443AggregateError
Cause 1 of 2
The network requires a proxy and Node.js does not use one
1Check
Node.js turns proxy support on only when NODE_USE_ENV_PROXY=1 or --use-env-proxy is set (added in 24.5.0 and 22.21.0). Without it, Node.js does not route requests through the proxy variables.
env | grep -i -E "proxy"2Fix
Start Node.js with env-proxy support, keeping the variables you already have. Add hosts that must skip the proxy to NO_PROXY.
NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node app.js
# or
node --use-env-proxy app.js3Verify
Run the request again; it should return a status code.
node --use-env-proxy -e "fetch('https://example.com').then(r=>console.log(r.status))"Confirmed by nodejs.org
Cause 2 of 2
The host has an IPv6 address that does not route, and the attempt window is short
1Check
Node.js tries all addresses with a family auto-detection algorithm (on by default since v20) and gives one AggregateError when all fail. Each attempt waits only autoSelectFamilyAttemptTimeout milliseconds before the next address is tried.
node -e "const n=require('net');console.log(n.getDefaultAutoSelectFamily(), n.getDefaultAutoSelectFamilyAttemptTimeout())"2Fix
Best: fix the IPv6 route or the AAAA record. As a workaround in code, raise the attempt timeout, or turn family auto-detection off for the process.
import net from 'node:net';
net.setDefaultAutoSelectFamilyAttemptTimeout(1000);
// or, as a blunt workaround:
// net.setDefaultAutoSelectFamily(false);3Verify
Run the failing request again from the same host.
node -e "fetch('https://example.com').then(r=>console.log(r.status))"Confirmed by nodejs.org
How do I stop it coming back?
- Keep proxy settings in the service's environment file so every process gets them.
- Test new servers with curl -4 and curl -6 before you publish an AAAA record.
- Set a request timeout in your HTTP client and log the target address when it fires.
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
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 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 fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fix