Node.js request fails with getaddrinfo EAI_AGAIN
Error: getaddrinfo EAI_AGAIN api.example.comShort answer
EAI_AGAIN means the system resolver asked a name server and got a temporary failure back. It is a DNS problem, not a bug in your code. Test the lookup from the same host or container, then fix the resolver list: wrong or unreachable DNS servers, or a container that cannot reach the host's DNS.
Fix it fast
1Find out which cause you have
Resolve the same name the way Node.js does, using the system resolver, from the exact place the app runs (host, container or CI job).
node -e "require('dns').lookup('example.com', console.log)" getent hosts example.com2Match what you see, then jump to its fix
- 1
getent hosts also prints nothing, and other tools on the same machine cannot resolve names eitherThe machine's DNS servers are unreachable or misconfiguredFix - 2
The same lookup works on the host but fails inside docker run or ComposeA container cannot reach the DNS server it was givenFix - 3
getent works; Node.js throws EAI_AGAIN or ENOTFOUNDLookups fail only inside Node.js while other tools resolveFix
- 1
What does the error look like?
Error: getaddrinfo EAI_AGAIN api.example.comerrno: -3001, code: 'EAI_AGAIN', syscall: 'getaddrinfo'
Cause 1 of 3
The machine's DNS servers are unreachable or misconfigured
1Check
dns.lookup() calls getaddrinfo(3), and EAI_AGAIN is the code for a temporary failure indication from the name server. So look at which servers the machine is asking.
resolvectl status
cat /etc/resolv.conf2Fix
Point the interface at a working resolver (your provider's or a public one), or fix the network rule that blocks UDP and TCP port 53. Then retry.
# Ubuntu with systemd-resolved: set DNS for a quick test
sudo resolvectl dns eth0 1.1.1.1 8.8.8.8
resolvectl query example.com3Verify
The lookup returns an address.
node -e "require('dns').lookup('example.com', console.log)"Confirmed by man7.org
Cause 2 of 3
A container cannot reach the DNS server it was given
1Check
Containers get a copy of the host's resolver settings, and on custom networks Docker's embedded DNS at 127.0.0.11 forwards to the host's servers. A loopback address copied from the host points at the container itself and goes nowhere.
docker run --rm busybox cat /etc/resolv.conf
docker run --rm busybox nslookup example.com2Fix
Give the container a real DNS server with --dns, or the dns key in Compose.
docker run --dns 1.1.1.1 --dns 8.8.8.8 my-image
# compose.yaml
services:
app:
dns:
- 1.1.1.1
- 8.8.8.83Verify
Run the lookup inside the container.
docker compose exec app node -e "require('dns').lookup('example.com', console.log)"Confirmed by docs.docker.com
Cause 3 of 3
Lookups fail only inside Node.js while other tools resolve
1Check
dns.lookup() runs getaddrinfo on the libuv threadpool and follows the operating system's rules, while dns.resolve*() sends its own network query and ignores /etc/hosts. Comparing the two shows whether the system resolver or the network path is to blame.
node -e "const d=require('dns');d.lookup('example.com',console.log);d.resolve4('example.com',console.log)"2Fix
If resolve4 works and lookup fails, fix the system resolver (first cause). If both fail, the network path to the DNS server is the problem. Do not hide it by switching APIs without knowing why.
cat /etc/nsswitch.conf | grep hosts3Verify
Both calls return addresses.
node -e "const d=require('dns');d.lookup('example.com',console.log);d.resolve4('example.com',console.log)"Confirmed by nodejs.org
How do I stop it coming back?
- List at least two DNS servers on every server and in every container network.
- Log the host name together with the error code so a bad name is not mistaken for a DNS outage.
- Retry outbound calls with a short back-off; EAI_AGAIN is described as temporary.
- Add a DNS check to your uptime monitoring, from inside the container as well as the host.
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 https request fails with getaddrinfo ENOTFOUND
getaddrinfo ENOTFOUND
ENOTFOUND means the name lookup failed before any connection was made.
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