How to fix Error: getaddrinfo ENOTFOUND api.example.com (DNS failure) in Node.js

What this error means

The ENOTFOUND error is Node.js's way of indicating that the DNS (Domain Name System) resolution failed for a requested hostname. When you make a network request to a domain like "api.example.com", Node.js uses the getaddrinfo system call to translate that human-readable hostname into an IP address that the network stack can use. This error means the DNS resolver returned "not found" - either the hostname doesn't exist, the DNS servers couldn't be reached, or there's a configuration issue preventing proper name resolution. The error originates from Node.js's DNS module, which wraps the operating system's DNS resolution functionality. Unlike connectivity errors (ECONNREFUSED) or timeout errors (ETIMEDOUT), ENOTFOUND specifically indicates a failure at the DNS lookup stage before any network connection is even attempted. This is often one of the first errors developers encounter when working with external APIs or databases.

Typical symptoms

• Network requests fail immediately with "getaddrinfo ENOTFOUND"
• Error occurs before any HTTP connection is established
• Same code works on other machines or networks
• Error includes the exact hostname that failed to resolve
• Localhost connections work but external domains fail
• Application crashes with unhandled promise rejection if not caught
• CI/CD pipelines fail at network request steps

Common causes

1. Typo or misspelling in the hostname or domain name
2. Missing protocol causes Node.js to interpret entire URL as hostname
3. DNS server is unreachable or not responding
4. No internet connectivity or firewall blocking DNS traffic
5. Incorrect /etc/hosts configuration for localhost mappings
6. Domain name has expired or does not exist
7. VPN or proxy configuration interfering with DNS resolution
8. IPv6 DNS resolution failing when only IPv4 is available
9. Corporate network blocking external DNS queries
10. Environment variable containing wrong hostname value

How to fix "Error: getaddrinfo ENOTFOUND api.example.com (DNS failure)"

// WRONG - includes protocol in hostname
const options = {
  hostname: 'https://api.example.com', // ❌ Error!
  path: '/data'
};

// CORRECT - hostname without protocol
const options = {
  hostname: 'api.example.com', // ✓
  path: '/data'
};

// With fetch or axios, use complete URL
const response = await fetch('https://api.example.com/data'); // ✓

const hostname = process.env.API_HOST;
console.log('Connecting to:', hostname); // Verify this is correct

import { lookup } from 'dns';
import { promisify } from 'util';

const lookupAsync = promisify(lookup);

async function testDNS() {
  try {
    const result = await lookupAsync('api.example.com');
    console.log('DNS resolved:', result);
  } catch (err) {
    console.error('DNS lookup failed:', err.code);
    // Returns ENOTFOUND if DNS fails
  }
}

testDNS();

# Test if DNS servers are reachable
ping 8.8.8.8

# Test DNS resolution with system tools
nslookup api.example.com
dig api.example.com

# Check which DNS servers you're using
cat /etc/resolv.conf  # Linux/macOS

async function makeRequest(url) {
  try {
    const response = await fetch(url);
    return await response.json();
  } catch (err) {
    if (err.code === 'ENOTFOUND') {
      console.error(`DNS lookup failed for: ${url}`);
      console.error('Check hostname spelling and DNS configuration');
      // Maybe retry with different DNS or fallback URL
    } else if (err.code === 'ECONNREFUSED') {
      console.error('Connection refused - service may be down');
    } else if (err.code === 'ETIMEDOUT') {
      console.error('Request timed out');
    } else {
      console.error('Request failed:', err.message);
    }
    throw err;
  }
}

import axios from 'axios';

try {
  const { data } = await axios.get('https://api.example.com/data');
} catch (err) {
  if (err.code === 'ENOTFOUND') {
    console.error('DNS failed:', err.hostname);
  }
  console.error('Full error:', err.toJSON());
}

# Edit hosts file (requires sudo)
sudo nano /etc/hosts

# Ensure these lines exist:
127.0.0.1       localhost
::1             localhost

C:\Windows\System32\drivers\etc\hosts

127.0.0.1       localhost
::1             localhost

# macOS
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

# Linux
sudo systemd-resolve --flush-caches

# Windows (as Administrator)
ipconfig /flushdns

Advanced notes

import { Resolver } from 'dns';
import { promisify } from 'util';

const resolver = new Resolver();
const resolve4 = promisify(resolver.resolve4.bind(resolver));
const dnsCache = new Map();

async function cachedLookup(hostname) {
  if (dnsCache.has(hostname)) {
    const cached = dnsCache.get(hostname);
    if (Date.now() < cached.expiry) {
      return cached.address;
    }
  }

  const addresses = await resolve4(hostname);
  const address = addresses[0];

  dnsCache.set(hostname, {
    address,
    expiry: Date.now() + 300000 // 5 minutes
  });

  return address;
}

import https from 'https';

const agent = new https.Agent({
  keepAlive: true,
  keepAliveMsecs: 30000,
  maxSockets: 50
});

// With fetch
fetch('https://api.example.com/data', { agent });

// With axios
import axios from 'axios';
const client = axios.create({
  httpsAgent: agent
});

import { lookup } from 'dns';
import { promisify } from 'util';

const lookupIPv4 = promisify((hostname, callback) => {
  lookup(hostname, { family: 4 }, callback);
});

const ipv4Address = await lookupIPv4('api.example.com');

import { Resolver } from 'dns';

const resolver = new Resolver();
resolver.setServers([
  '8.8.8.8',      // Google DNS
  '1.1.1.1',      // Cloudflare DNS
  '208.67.222.222' // OpenDNS
]);

const addresses = await resolver.resolve4('api.example.com');

# docker-compose.yml
services:
  app:
    dns:
      - 8.8.8.8
      - 1.1.1.1
    dns_search:
      - example.com

import { lookup } from 'dns';

lookup('api.example.com', { all: true, verbatim: true }, (err, addresses) => {
  if (err) {
    console.error('DNS Error:', {
      code: err.code,
      syscall: err.syscall,
      hostname: err.hostname
    });
  } else {
    console.log('Resolved addresses:', addresses);
  }
});

Frequently asked questions

What does "ENOTFOUND" mean?

js's way of indicating that the DNS (Domain Name System) resolution failed for a requested hostname. js uses the getaddrinfo system call to translate that human-readable hostname into an IP address that the network stack can use. This error means the DNS resolver returned "not found" - either the hostname doesn't exist, the DNS servers couldn't be reached, or there's a configuration issue preventing proper name resolution.

How do I fix "ENOTFOUND"?

This error occurs when Node.js cannot resolve a hostname to an IP address through DNS lookup. It commonly happens with network requests using fetch, axios, or http when the domain name is misspelled, the DNS server is unreachable, or the hostname does not exist.

What causes "ENOTFOUND"?

Typo or misspelling in the hostname or domain name Missing protocol causes Node.js to interpret entire URL as hostname DNS server is unreachable or not responding

Is the "ENOTFOUND" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Error: EPERM: operation not permitted, chmod 'file'

  EPERM: operation not permitted (chmod/file operations)

  HIGH

• Error: getaddrinfo ENOTFOUND example.com

  getaddrinfo ENOTFOUND - DNS lookup failed

  MEDIUM

• Error: EPIPE: broken pipe (write to closed stream)

  EPIPE: Broken pipe when writing to closed stream

  MEDIUM

• Error: ENOTEMPTY: directory not empty, rmdir 'dirname'

  ENOTEMPTY: directory not empty when removing directory

  MEDIUM

• Error: zlib error Z_DATA_ERROR (corrupted compressed data)

  Z_DATA_ERROR: Corrupted compressed data

  MEDIUM

• Error: Could not find package.json in current directory (npm module resolution)

  How to fix "Could not find package.json in current directory" in Node.js

  MEDIUM

Official resources & further reading

• 📚Node.js Official Documentation
• 📖
  Node.js DNS Module Documentation(Official Docs)
• 🐙
  dns.lookup() returns ENOTFOUND if no response in 3500ms(GitHub)
• 🐙
  DNS lookup fails sometimes when done in batch(GitHub)
• 📝
  How to Fix the getaddrinfo ENOTFOUND Error in Node.js