ENOTFOUND

What is ENOTFOUND?

ENOTFOUND stands for 'Entry Not Found'. In Node.js networking, it indicates that a DNS lookup (getaddrinfo) failed to resolve the given hostname into an IP address. This occurs if there is a typo in the hostname, if your DNS server is offline, or if you lack internet connectivity.

Common Causes

• Hostname Typos: Providing paths or protocols in the hostname query (e.g. 'http://api.com' instead of 'api.com').
• Network Offline: Local internet or container DNS resolvers are offline.
• Missing Host Mapping: Querying custom local hostnames without defining them in the /etc/hosts file.

Common Mistakes

• Passing the protocol (like http://) inside host lookup parameters (e.g. dns.lookup('http://google.com') will throw ENOTFOUND; pass 'google.com' instead).
• Assuming local containers can resolve hostnames without adding Docker service networks.

How to Fix

Framework-Specific Examples

app.get('/service', async (req, res, next) => {
  try {
    await axios.get('https://invalid-api-domain.com');
  } catch (err) {
    if (err.code === 'ENOTFOUND') {
      return res.status(502).json({ error: 'Upstream gateway DNS resolution failed.' });
    }
    next(err);
  }
});

Server Configuration Examples

resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;

Best Practices

• Validate URL syntax configurations dynamically before parsing hostnames.
• Monitor DNS health queries.

Frequently Asked Questions (FAQ)