Maaz Zindani

Loading the index…

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

Node.js request fails with getaddrinfo EAI_AGAIN

ErrorError: getaddrinfo EAI_AGAIN api.example.com

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

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

Fix it fast

  1. 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.com
  2. 2Match what you see, then jump to its fix

    1. 1getent hosts also prints nothing, and other tools on the same machine cannot resolve names eitherThe machine's DNS servers are unreachable or misconfiguredFix
    2. 2The same lookup works on the host but fails inside docker run or ComposeA container cannot reach the DNS server it was givenFix
    3. 3getent works; Node.js throws EAI_AGAIN or ENOTFOUNDLookups fail only inside Node.js while other tools resolveFix

What does the error look like?

  • Error: getaddrinfo EAI_AGAIN api.example.com
  • errno: -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.conf

2Fix

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

3Verify

The lookup returns an address.

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

Confirmed by man7.org

Did this fix it?

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

2Fix

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

3Verify

Run the lookup inside the container.

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

Confirmed by docs.docker.com

Did this fix it?

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 hosts

3Verify

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

Did this fix it?

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:

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.