Node.js "getaddrinfo ENOTFOUND" - DNS Lookup Failed in Tests in CI

Node could not resolve a hostname to an IP address. In CI tests this is either a transient DNS failure or a test that reaches a host the runner cannot resolve (a service alias or an external API).

What this error means

A test fails with getaddrinfo ENOTFOUND <host>. The host name is correct, but resolution fails - sometimes intermittently, sometimes because the test should not hit the network at all.

Error: getaddrinfo ENOTFOUND api.internal.test
    at GetAddrInfoReqWrap.onlookup (node:dns:107:26)
  errno: -3008,
  code: 'ENOTFOUND',
  hostname: 'api.internal.test'

Common causes

Transient DNS resolution failure

The runner momentarily could not resolve the host. This is intermittent and typically passes on retry.

A test reaching an unresolvable host

A test points at a service alias or external API the CI runner cannot resolve, when it should target a mock or localhost.

How to fix it

Mock or point tests at localhost

Tests should not depend on external DNS. Use a mock server or a known local host.

1. Replace external hosts with a local mock or fixture server.
2. Inject the base URL via env so tests target 127.0.0.1.
3. Reserve real-network calls for a separate, retryable integration suite.

Retry genuinely transient DNS blips

For integration tests that must hit the network, add a bounded retry around the resolving call.

1. Wrap the resolving call (fetch/connect) in a bounded retry.
2. Treat ENOTFOUND as retryable with a small backoff.
3. Cap retries so a truly unresolvable host still fails fast.

How to prevent it

• Keep unit tests off the network with mocks and localhost.
• Inject hostnames via env so they are environment-aware.
• Isolate real-network integration tests into a retryable suite.

Related guides