# Node.js: “Error: getaddrinfo ENOTFOUND hostname”
> Error: getaddrinfo ENOTFOUND host. The hostname did not resolve: a typo, a URL passed as a host, an unset env variable, a Docker service name, or DNS and VPN.
Canonical: https://app369.com/fix/node-getaddrinfo-enotfound/
Last updated: 2026-11-08
A request or database connection fails with Error: getaddrinfo ENOTFOUND api.example.com (sometimes ENOTFOUND undefined). Before connecting, Node.js asked the operating system for the IP address of that hostname, and got no answer. Nothing was sent to the server; the name itself could not be found.
**Short answer**
Read the hostname at the end of the message. If it says undefined, an environment variable is not set. If it contains https:// or a path, a full URL was passed where only a hostname belongs. Otherwise check the spelling, then resolve the name with Node.js itself from the same machine or container. If the name is a Docker Compose service such as db, it only exists inside the Compose network, so from your machine use localhost and the published port. Inside a company network, check that the VPN or DNS can resolve the name.
## **Why the hostname did not resolve, and the fix**
1. 01 ### **An unset variable or a URL used as a host**
> “ENOTFOUND (DNS lookup failed): Indicates a DNS failure of either EAI_NODATA or EAI_NONAME.” [**Node.js, Errors: common system errors**](https://nodejs.org/api/errors.html) ENOTFOUND undefined means the host came from a missing environment variable. A host value such as https://db.example.com fails because the scheme is part of the name. Pass a plain hostname to options that take a host, and a full URL only to options that take a URL.```
const https = require('node:https');
// wrong: host includes the scheme
https.request({ host: 'https://api.example.com', path: '/v1' });
// right
https.request({ host: 'api.example.com', path: '/v1' });
if (!process.env.DB_HOST) throw new Error('DB_HOST is not set');
```
2. 02 ### **A Docker Compose service name used outside Compose** A Compose service name such as db only resolves inside the same Compose network. ENOTFOUND db usually means Node.js is running on your machine, outside Compose, with @db: in its connection string, or the two services are on different networks, or the name is misspelled. From your machine, use localhost and the published port. (Using localhost inside a container gives ECONNREFUSED instead, because localhost is the container itself.)```
# docker-compose.yml: the app reaches the database as host "db"
services:
db:
image: postgres:17
app:
environment:
DATABASE_URL: postgres://app:secret@db:5432/app
```
3. 03 ### **DNS, VPN or offline**
> “dns.lookup() uses the operating system facilities to perform name resolution.” [**Node.js, DNS: dns.lookup()**](https://nodejs.org/api/dns.html) Internal hostnames resolve only on the company network or VPN, and a broken DNS setting or captive Wi-Fi breaks every name. nslookup asks DNS servers directly and can disagree with Node.js, which uses the system resolver (hosts file, VPN split DNS). The node line below is the real test.```
nslookup api.example.com
node -e "require('dns').lookup('api.example.com', console.log)"
```
4. 04 ### **A wrong or retired hostname** A typo, a staging host that was removed, a deleted database project, or a host copied wrongly from a dashboard gives the same error. Copy the hostname again from the provider and compare it character by character.
Checked against the vendor’s docs on November 8, 2026: [Node.js: Errors (common system errors)](https://nodejs.org/api/errors.html); [Node.js: DNS](https://nodejs.org/api/dns.html).
## **Rather hand it over?**
Fixed scope, fixed price, paid upfront. The work happens in writing; no call needed.
- [from $450**App Fix Ticket**One reproducible bug in an existing mobile or web app, diagnosed and fixed.**See scope and start**](https://app369.com/fixed-price/flutter-firebase-bug-fix/)
- [from $450**AI-Built App Rescue**A Lovable, Bolt or Cursor app checked end to end in 3 days, then its worst problems fixed at a fixed price.****No issues worth fixing, no charge.**** If the Launch Check finds nothing rated medium or higher, Simon refunds the full $450. You keep the report either way. This applies to the first 10 Launch Checks bought after October 30, 2026.**See scope and start**](https://app369.com/fixed-price/ai-app-rescue/)
Related: [**ECONNREFUSED: connection refused**](https://app369.com/fix/econnrefused-connection-refused/) · [**Node.js ECONNRESET (“socket hang up”)**](https://app369.com/fix/node-econnreset/) · [**Prisma “Can’t reach database server” with Supabase**](https://app369.com/fix/supabase-prisma-cant-reach-database/) · [**“self-signed certificate in certificate chain”**](https://app369.com/fix/node-self-signed-certificate-in-chain/)
Questions
## **More on this error**
**What is the difference between ENOTFOUND and ECONNREFUSED? **+
ENOTFOUND means the hostname could not be turned into an IP address. ECONNREFUSED means the address was found, but nothing accepted the connection on that port.
**It fails only sometimes. Why? **+
Usually a flaky resolver or network: Wi-Fi changes, VPN reconnects, or DNS rate limits in a busy container. Temporary DNS failures often show as getaddrinfo EAI_AGAIN rather than ENOTFOUND. If it keeps happening in production, cache lookups or check the DNS settings of the host.
**Can you fix it for me? **+
If one bug is the whole problem, the App Fix Ticket covers it: a written diagnosis first, then the fix. If the app has more going on, the Launch Check is a written check of the whole app. Each issue found is rated critical, high, medium or low, with where it is and how it was confirmed. No issues worth fixing, no charge. If the Launch Check finds nothing rated medium or higher, Simon refunds the full $450. You keep the report either way. This applies to the first 10 Launch Checks bought after October 30, 2026.
A different error?
## **Describe it and get a written quote**
Send the error and what you were doing. You get a written scope, a fixed price and a timeline; Simon replies by email, usually within one business day.
[**Describe your problem **→](https://app369.com/contact/) [**All fixes**](https://app369.com/fix/)