Maaz Zindani

Loading the index…

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

Node.js fails with connect ETIMEDOUT while the same URL opens in a browser

ErrorError: connect ETIMEDOUT 203.0.113.10:443

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

  • Applies to Node.js 22.21+, Node.js 24.5+
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1env | 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. 2curl -4 works and curl -6 hangs or failsThe host has an IPv6 address that does not route, and the attempt window is shortFix

What does the error look like?

  • Error: connect ETIMEDOUT 203.0.113.10:443
  • AggregateError

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

3Verify

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

Did this fix it?

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

Did this fix it?

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

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 fix

Back 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 fix

Next step

Want this handled for good?

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