Node.js errorNode.js: “Error: getaddrinfo ENOTFOUND hostname”

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

   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()

   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); Node.js: DNS.

Rather hand it over?

Fixed scope, fixed price, paid upfront. The work happens in writing; no call needed.

• from $450App Fix TicketOne reproducible bug in an existing mobile or web app, diagnosed and fixed.See scope and start
• from $450AI-Built App RescueA 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

Related: ECONNREFUSED: connection refused · Node.js ECONNRESET (“socket hang up”) · Prisma “Can’t reach database server” with Supabase · “self-signed certificate in certificate chain”