Node.js https request fails with getaddrinfo ENOTFOUND
Error: getaddrinfo ENOTFOUND api.example.comShort 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.
Fix it fast
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.com2Match what you see, then jump to its fix
- 1
The 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
dns.lookup also fails, and so does pingThe name does not exist or the system cannot resolve itFix - 3
The host resolves the name, but the same lookup fails inside the containerThe app runs in a container that has no working DNSFix
- 1
What does the error look like?
Error: getaddrinfo ENOTFOUND api.example.comgetaddrinfo 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.jsConfirmed by nodejs.org
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/hosts2Fix
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/hosts3Verify
The lookup now returns an address.
node -e "require('dns').lookup('api.internal.example', console.log)"Confirmed by nodejs.org
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-image3Verify
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
Node.js request fails with getaddrinfo EAI_AGAIN
errno: -3001, code: 'EAI_AGAIN', syscall: 'getaddrinfo'
EAI_AGAIN means the system resolver asked a name server and got a temporary failure back.
3 causes, each with a fixBack end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack 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 fixBack end
Puppeteer cannot start Chrome on a Linux server
error while loading shared libraries: libnss3.so: cannot open shared object file
Puppeteer prints the real reason below the first line, so read that.
4 causes, each with a fixBack 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 fix