Maaz Zindani

Loading the index…

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

Node.js https request fails with getaddrinfo ENOTFOUND

ErrorError: getaddrinfo ENOTFOUND api.example.com

Short answer

ENOTFOUND means the name lookup failed before any connection was made. Print the exact host Node tried. Often a protocol or path ended up inside the host option, or the name is misspelled. Otherwise the machine or container cannot resolve names, and the same lookup fails for ping.

  • Applies to Node.js 22, Node.js 24, Docker Engine, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the hostname in the error, then resolve it the way Node does. dns.lookup uses the same system call as most programs, so it should agree with ping.

    node -e "require('dns').lookup('api.example.com', console.log)"
    ping -c 1 api.example.com
  2. 2Match what you see, then jump to its fix

    1. 1The name in the error contains https:// or a slash, for example ENOTFOUND https://api.example.comA URL or path was put in the host optionFix
    2. 2dns.lookup also fails, and so does pingThe name does not exist or the system cannot resolve itFix
    3. 3The host resolves the name, but the same lookup fails inside the containerThe app runs in a container that has no working DNSFix

What does the error look like?

  • Error: getaddrinfo ENOTFOUND api.example.com
  • getaddrinfo ENOTFOUND

Cause 1 of 3

A URL or path was put in the host option

1Check

In http.request and https.request the host option is a domain name or IP address, nothing more. A scheme or path there is looked up as a name and cannot be found.

grep -rn "host:" src/ | grep -E "https?://"

2Fix

Pass a full URL string as the first argument (Node parses it with new URL()), or pass only the bare name in host and the rest in path.

const https = require('node:https');
https.get('https://api.example.com/v1/items', (res) => { /* ... */ });
// or
https.get({ host: 'api.example.com', path: '/v1/items' }, (res) => { /* ... */ });

3Verify

Run the request again; the error should change to a normal response or a different error.

node request.js

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The name does not exist or the system cannot resolve it

1Check

dns.lookup uses the operating system, so it resolves like the ping command. The Node.js docs also say this lookup is controlled by nsswitch.conf and resolv.conf on POSIX systems, and that dns.resolve skips /etc/hosts.

cat /etc/resolv.conf
grep api.example.com /etc/hosts

2Fix

Correct a misspelled name, fix the DNS server in your network settings, or add a deliberate entry to /etc/hosts for an internal name. Remember that changing these files affects every program on the machine.

echo '203.0.113.10 api.internal.example' | sudo tee -a /etc/hosts

3Verify

The lookup now returns an address.

node -e "require('dns').lookup('api.internal.example', console.log)"

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

The app runs in a container that has no working DNS

1Check

Containers inherit the host's DNS settings by default, and on user-defined networks they use Docker's embedded DNS server at 127.0.0.11. A host with a VPN or a local-only resolver can break that chain.

docker exec my-app cat /etc/resolv.conf
docker exec my-app node -e "require('dns').lookup('api.example.com', console.log)"

2Fix

Give the container an explicit DNS server with --dns (repeat the flag for several servers).

docker run --dns 1.1.1.1 --dns 8.8.8.8 my-image

3Verify

Repeat the lookup inside the container.

docker exec my-app node -e "require('dns').lookup('api.example.com', console.log)"

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Read hostnames from one config value that holds only the name, and build the URL in one place.
  • Log the full error, including the hostname, so a malformed host is obvious.
  • Test name resolution from inside the container or server that runs the app, not only from your laptop.

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

Puppeteer cannot start Chrome in an Alpine Docker image

Could not find expected browser locally

On Alpine, the Chrome that Puppeteer downloads does not run, and a hard-coded path such as /usr/bin/chromium-browser points at nothing if Chromium is not installed there.

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