Skip to content
Puppeteer · error message

Puppeteer: net::ERR_NAME_NOT_RESOLVED at <url>

ConfigurationNavigation & network

Last verified

The exact message
Error: net::ERR_NAME_NOT_RESOLVED at https://exmaple.com/

What it means

page.goto() rejected because Chrome could not resolve the hostname to an IP address. Puppeteer passes Chrome's network error text through and appends at plus the URL. The same pattern covers related network failures you may see from the same call: net::ERR_CONNECTION_REFUSED (nothing listening on that port), net::ERR_CONNECTION_TIMED_OUT, and net::ERR_CERT_AUTHORITY_INVALID for TLS problems.

Because DNS failed, no request was sent and no response exists. The error arrives immediately rather than after the navigation timeout, and retrying the same URL from the same machine will keep failing until the name or the resolver changes.

What is not wrong: your selectors, waits and page logic. The site may also be perfectly healthy for everyone else; the problem is the name you used or the network the browser sits on.

What it looks like

try {
  await page.goto(url, { waitUntil: 'domcontentloaded' });
} catch (err) {
  if (/net::ERR_NAME_NOT_RESOLVED/.test(err.message)) {
    console.warn(`DNS failed for ${url}`);
  } else {
    throw err;
  }
}

Why it happens

  • A typo or an empty environment variable in the URL.
  • An internal hostname (VPN, intranet, docker-compose service) used from a machine that cannot resolve it.
  • The container or serverless runtime has no outbound DNS or requires a proxy.
  • A proxy configured via --proxy-server that cannot resolve or reach the host.
  • The domain has expired or its DNS records were removed.

How to fix it

  1. Log the exact URL and test it from the same environment with nslookup or curl -I.
  2. Validate configuration before launching: fail fast if the base URL is missing.
  3. In docker-compose, put the browser on the same network and use the service name.
  4. If a proxy is required, pass args: ['--proxy-server=http://proxy:3128'] and authenticate with page.authenticate().
  5. Catch the error and record it as a dead link instead of retrying indefinitely.

How to stop it recurring

Validate URLs and environment variables at startup, and run browser jobs on a network that can resolve every host they visit. In crawlers, classify net:: errors separately from timeouts so dead domains are skipped rather than retried, and record the failing hostname so configuration mistakes stand out in logs.

Official documentation: pptr.dev/api/puppeteer.page.goto. See all Puppeteer error messages.

Related errors

Definitions

Quick answers

What does "net::ERR_NAME_NOT_RESOLVED at <url>" mean in Puppeteer?

page.goto() rejected because Chrome could not resolve the hostname to an IP address. Puppeteer passes Chrome's network error text through and appends at plus the URL. The same pattern covers related network failures you may see from the same call: net::ERR_CONNECTION_REFUSED (nothing listening on that port), net::ERR_CONNECTION_TIMED_OUT , and net::ERR_CERT_AUTHORITY_INVALID for TLS problems.

How do I fix "net::ERR_NAME_NOT_RESOLVED at <url>"?

1. Log the exact URL and test it from the same environment with nslookup or curl -I. 2. Validate configuration before launching: fail fast if the base URL is missing. 3. In docker-compose, put the browser on the same network and use the service name. 4. If a proxy is required, pass args: ['--proxy-server=http://proxy:3128'] and authenticate with page.authenticate(). 5. Catch the error and record it as a dead link instead of retrying indefinitely.

Run browser automation you can watch and take over

Autonoly runs each job in a real cloud Chromium browser driven by Playwright. Timeouts and detached elements still happen; the difference is that you can watch the run live, see the step that failed, and take control of the browser to finish it.

Also see Live browser control.