Maaz Zindani

Loading the index…

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

Node.js request fails with connect ENETUNREACH

ErrorError: connect ENETUNREACH 2a03:2880:f12f:83:face:b00c:0:25de:443

Short answer

ENETUNREACH means the operating system has no route to the address Node.js tried (Linux: Network is unreachable). The usual reason is that a host name resolves to an IPv6 address first and the server has no IPv6 route. Prefer IPv4 in DNS ordering, or make sure address auto-selection is on.

  • Applies to Node.js 20, Node.js 22, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the address in the error message. An IPv6 address (it contains colons) points to the first cause; an IPv4 address means the whole network path is blocked, which is outside Node.js.

    node -e "require('dns').lookup('example.com', { all: true }, (e, a) => console.log(e || a))"
  2. 2Match what you see, then jump to its fix

    1. 1The address in the error is IPv6; the same request to an IPv4 address worksThe host resolves to IPv6 first and this machine has no IPv6 routeFix
    2. 2Only one address is attempted and the error appears even though another address of the host would workTrying every address is switched offFix

What does the error look like?

  • Error: connect ENETUNREACH 2a03:2880:f12f:83:face:b00c:0:25de:443

Cause 1 of 2

The host resolves to IPv6 first and this machine has no IPv6 route

1Check

Since Node.js 17 the default DNS result order is verbatim, meaning addresses are used in the order the resolver returns them, so an AAAA record can come first.

node -p "require('dns').getDefaultResultOrder()"

2Fix

Tell Node.js to put IPv4 first, in code before the first request or with the command-line flag. Note that a setting made in the main thread does not apply to worker threads.

// at the top of your entry file
require('dns').setDefaultResultOrder('ipv4first');

# or when starting
node --dns-result-order=ipv4first server.js

3Verify

Repeat the failing request; the lookup now lists the IPv4 address first.

node --dns-result-order=ipv4first -e "require('dns').lookup('example.com', (e, a, f) => console.log(a, f))"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 2

Trying every address is switched off

1Check

Address auto-selection (autoSelectFamily) tries the returned IPv6 and IPv4 addresses in turn and loosely follows RFC 8305. It is on by default from Node.js 20.0.0 (and 18.18.0). Older runtimes, or code and flags that turned it off, fail on the first address. When every attempt fails you get an AggregateError.

node -p "require('net').getDefaultAutoSelectFamily()"

2Fix

Turn it on for the whole process, and optionally give each attempt a shorter timeout.

const net = require('net');
net.setDefaultAutoSelectFamily(true);
net.setDefaultAutoSelectFamilyAttemptTimeout(250);

3Verify

The check command prints true and the request succeeds through the reachable address.

node -p "require('net').getDefaultAutoSelectFamily()"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Run Node.js 20 or later so address auto-selection is on by default.
  • If a server has no IPv6, set the DNS result order explicitly in your start script.
  • Log the address from the error; it tells you immediately which family failed.

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.