ENOTFOUND 🔌 API

Error: getaddrinfo ENOTFOUND host / Name or service not known

DNS lookup for the hostname failed — the name is wrong, doesn’t exist, or this machine can’t resolve it.

Seen on: Linux Node.js Python Docker

Meaning

Before connecting, the client resolves the hostname to an IP. ENOTFOUND (Node), socket.gaierror / “Name or service not known” (Python, Linux) and “Could not resolve host” (curl) all mean that step failed.

Common causes

  • Typo in hostname, or protocol included in a host field (https://api.x.com where only api.x.com is expected)
  • Internal hostname not resolvable from this network/container
  • Docker service name used outside the compose network
  • DNS server down / no internet / VPN required
  • Domain expired or DNS record removed

⚡ Quick fix

  1. Resolve it yourself: nslookup host or dig host
  2. Pass only the hostname where a host is expected (no scheme, no path)
  3. Check VPN / corporate DNS, and /etc/resolv.conf inside containers
  4. In Docker Compose, call services by their service name from inside the network

Detailed fix by platform

Linux

  1. Check DNS from the same machine/container:
    bash
    nslookup api.example.com
dig +short api.example.com
cat /etc/resolv.conf
docker compose exec app getent hosts db

How to diagnose

  1. Hostname — Exactly what string is resolved?
  2. DNS — Does nslookup work here?
  3. Network — VPN, container network or offline?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.