Error: getaddrinfo ENOTFOUND
Your program asked the system to look up a host name and the answer was “not found”, so it couldn't connect.
Quick checks
- Look at the host in the error: `https://api.example.com` as a host name (with the scheme) can never resolve.
- Run `dig +short host` to check the name exists.
- Check for typos and environment-specific host names.
Fixes on Mac
Pass a host name, not a URL
- Options like
hostinhttp.requestexpectapi.example.com, nothttps://api.example.com/v1. Usenew URL()to split it.
- Options like
Check DNS and VPN
- Internal names (
db.internal) only resolve on the VPN; connect it. - Flush the cache:
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder.
- Internal names (
Check proxy settings
HTTPS_PROXYset to a dead proxy host gives ENOTFOUND for the proxy's name.
Fixes on Windows
Windows
nslookup hostto test; check proxy environment variables.
Other devices
Docker and CI
- Service names only resolve inside the same Docker network; check the network and container names.
Still not working?
If resolution works in Terminal but not in your app, the app may use a different resolver or proxy (some HTTP clients read proxy variables). Log the exact host string your code passes.
See what’s happening
LightAtom's connections view shows the domain behind each of your Node process's connections.
Frequently asked questions
What does getaddrinfo ENOTFOUND mean?
The DNS lookup for a host name failed: the name doesn't exist, can't be resolved on this network, or isn't a valid host name.
Why do I get ENOTFOUND for a URL?
Some APIs expect a host name, and a full URL with https:// isn't one. Pass only the host, or use an API that accepts URLs.
What is the difference between ENOTFOUND and EAI_AGAIN?
ENOTFOUND: the name definitely doesn't resolve. EAI_AGAIN: a temporary DNS failure, such as no network or a timeout; retrying may work.