ScreenshotNeo

BlogHow-to

How to Fix Puppeteer TimeoutError After 30 Seconds

Learn why Puppeteer times out after 30 seconds, which timeout to change, how to fix wait conditions, and how to troubleshoot navigation races.

By the ScreenshotNeo team30 September 20268 min read

How to Fix Puppeteer TimeoutError After 30 Seconds

A Puppeteer TimeoutError after 30 seconds means one awaited operation did not reach its expected condition before its timeout expired. The 30,000 millisecond value is the documented default for many wait operations; it is not proof that the website is broken or that every timeout should be increased. First identify the exact call in the stack trace, then choose the narrowest fix: a per-call timeout, a page-wide default, a navigation-specific default, or a better wait condition.

Puppeteer documents TimeoutError as an error emitted when certain operations are terminated because they exceeded a timeout. The same error can come from navigation, selector waits, response waits, or browser launch. The operation named in the stack trace tells you where to start.

What the 30-second timeout means

Most Puppeteer wait APIs use a default timeout of 30000 milliseconds. The WaitForOptions API documents this default and allows timeout: 0 to disable the limit. A timeout only measures how long Puppeteer waits for a condition. It does not explain why the condition was never met.

For example, these failures have different causes even though they can all occur at 30 seconds:

  • page.goto() is waiting for a navigation lifecycle event that never occurs.
  • page.waitForSelector('.ready') is waiting for a selector that is misspelled, hidden, or never rendered.
  • page.waitForNavigation() is waiting after a click that did not navigate.
  • page.waitForResponse() is waiting for a request whose URL or method does not match.
  • puppeteer.launch() cannot start the browser process.

Diagnose the failing operation first

  1. Read the complete stack trace and find the first application line that awaits Puppeteer.
  2. Record the method and predicate: URL, selector, response matcher, lifecycle event, or launch step.
  3. Run with a short diagnostic log around that call so you know whether the page reached the previous step.
  4. Check whether the expected event is possible on the target site. A longer timeout cannot make a selector appear or create a navigation that never happens.
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({headless: true});
  const page = await browser.newPage();

  console.log('before goto');
  await page.goto('https://example.com', {waitUntil: 'domcontentloaded', timeout: 45_000});
  console.log('after goto');

  console.log('before selector');
  await page.waitForSelector('h1', {timeout: 10_000});
  console.log('selector found');

  await browser.close();
})();

Use the operation-specific message from the error rather than treating every timeout as a navigation problem. Puppeteer’s TimeoutError reference lists timeout-producing operations, including waitForSelector and launch.

A timeout belongs to a specific awaited operation and its completion condition.
A timeout belongs to a specific awaited operation and its completion condition.

Fix a wait that legitimately needs more time

Set a timeout on the individual call when you know that one operation can take longer. Values are milliseconds.

await page.waitForSelector('.report-ready', {timeout: 60_000});
await page.waitForResponse(
  response => response.url().includes('/api/report') && response.ok(),
  {timeout: 60_000}
);

A per-call value keeps unrelated waits fast. If this change only moves the error from 30 seconds to 60 seconds, inspect the predicate and page state instead of increasing it repeatedly.

Change Puppeteer’s default timeout

page.setDefaultTimeout() changes the default for general wait operations on that page. It is useful when several selectors, functions, or responses in the same workflow share a known delay.

page.setDefaultTimeout(45_000);

await page.waitForSelector('#dashboard');
await page.waitForFunction(() => window.appReady === true);

The default applies broadly, so a typo in a selector may now take 45 seconds to fail. Keep the value close to the real operating limit and use per-call overrides for exceptional steps.

Change the navigation timeout separately

page.setDefaultNavigationTimeout() applies to navigation operations documented by Puppeteer: goBack, goForward, goto, reload, setContent, and waitForNavigation. Use it when the failing method is one of those calls.

page.setDefaultNavigationTimeout(60_000);
await page.goto('https://example.com', {waitUntil: 'networkidle2'});
await page.reload();

The navigation default is separate from the general page timeout. Set both only when your workflow needs both behaviors.

Choose the right navigation condition

goto() uses load as its default waitUntil condition. That event may be too strict for a page with long-lived connections, third-party resources, or a single-page application that renders content after the initial document loads.

Condition Use it when Common mistake
domcontentloaded You need the parsed document and can wait for application content separately. Assuming data fetched after parsing is already present.
load Required images, stylesheets, and subresources should finish. Using it on pages with slow or unreliable third-party assets.
networkidle0 The page should have no active network connections for the idle window. Using it on apps with analytics, polling, or web sockets.
networkidle2 A mostly idle network is a useful approximation. Treating it as proof that the application is ready.

For dynamic pages, combine a practical lifecycle event with the state your script actually needs:

await page.goto('https://example.com/app', {
  waitUntil: 'domcontentloaded',
  timeout: 45_000
});
await page.waitForSelector('[data-testid="results"]', {timeout: 30_000});

This makes the readiness requirement explicit. If the selector is not rendered for an empty result, wait for an application state that covers both the empty and populated cases.

Prevent click and navigation race conditions

When a click triggers navigation, start the navigation promise before resolving the click. Puppeteer warns that separately awaiting the click and then calling waitForNavigation() can miss the navigation event.

const navigation = page.waitForNavigation({
  waitUntil: 'domcontentloaded',
  timeout: 45_000
});
await page.click('a.next-page');
await navigation;

For a click that updates the current page without navigation, do not wait for navigation. Wait for the resulting selector, response, or application state instead.

Use a complete diagnostic script

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({headless: true});
  const page = await browser.newPage();
  page.setDefaultTimeout(30_000);
  page.setDefaultNavigationTimeout(45_000);

  page.on('console', message => console.log('[browser]', message.text()));
  page.on('pageerror', error => console.error('[page error]', error.message));
  page.on('requestfailed', request => {
    console.error('[request failed]', request.url(), request.failure()?.errorText);
  });

  try {
    await page.goto('https://example.com/app', {
      waitUntil: 'domcontentloaded',
      timeout: 45_000
    });
    await page.waitForSelector('#app-ready', {timeout: 20_000});
    const title = await page.title();
    console.log({title, url: page.url()});
  } catch (error) {
    console.error('Puppeteer operation failed:', error);
    await page.screenshot({path: 'timeout-debug.png', fullPage: true}).catch(() => {});
  } finally {
    await browser.close();
  }
})();

Common causes and fixes

The selector never appears

Check spelling, frame context, shadow DOM, visibility, and whether the page renders an empty state. Inspect await page.content() or take a screenshot immediately before the wait. If the element is inside an iframe, obtain the matching frame and wait there.

A cleanup step can remove common overlays before a screenshot is captured.
A cleanup step can remove common overlays before a screenshot is captured.

The URL redirects or never reaches the expected page

Log page.url() after navigation and inspect response status codes. Authentication redirects, consent pages, bot checks, and geo restrictions can leave your script on a different document. Wait for a selector that proves the intended page loaded.

networkidle never occurs

Analytics, polling, advertisements, and web sockets can keep connections open. Use domcontentloaded followed by a specific selector, or block unnecessary requests in a controlled test environment.

A click does not navigate

The click may open a new tab, update history through JavaScript, or only change content. Listen for a target event when a new page is expected, or wait for the resulting DOM or API response.

Browser launch times out

Launch failures are different from page waits. Check the installed browser, executable path, sandbox permissions in the runtime, and process limits. A page timeout setting does not repair a browser process that cannot start.

Increasing the timeout always delays the same error

Treat that pattern as evidence that the completion condition is wrong or unreachable. Recheck the selector, URL, frame, lifecycle event, authentication state, and network behavior.

Performance, reliability, and cost considerations

  • Keep waits semantic. Waiting for one application-ready selector is usually more predictable than waiting for every third-party request to finish.
  • Use bounded retries. Retry transient navigation or network failures with a small limit, but do not retry deterministic selector errors indefinitely.
  • Capture evidence on failure. Save the URL, HTML, console errors, failed requests, and a screenshot so the next investigation starts with page state.
  • Separate navigation and content budgets. A slow server response and a slow client-side render have different remedies and should have separate limits.
  • Control external resources. Ads, trackers, and chat scripts can add latency and make network-idle waits unreliable. Blocking them may improve repeatability when they are irrelevant to the task.
  • Do not disable timeouts casually. timeout: 0 is appropriate only when an unbounded wait is safe for the surrounding worker. Otherwise it can consume a browser slot forever.

Or skip the browser setup

If your goal is a clean website screenshot rather than browser automation, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response reports the result through X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for all options. The same endpoint supports PNG, JPEG, WebP, and PDF output, full-page shots with lazy images loaded, CSS-selector element capture, dark mode, device presets, custom viewports, retina scale, custom CSS and JavaScript, clicks, selector or network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous jobs, bulk capture, usage data, and an OpenAPI specification.

curl -G 'https://api.screenshotneo.com/v1/shot' -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get('https://api.screenshotneo.com/v1/shot', params={'access_key': 'YOUR_API_KEY', 'url': 'https://stripe.com'}, timeout=90)
open('shot.webp', 'wb').write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

Short FAQ

Can I set Puppeteer’s timeout to zero?

Yes. The documented wait option timeout: 0 disables that wait’s timeout. Use it only when an unbounded operation is acceptable.

Should I use 60 seconds for every wait?

No. Set a larger value only for operations with a demonstrated need. Keep selectors and navigation conditions specific so real failures surface promptly.

Does setDefaultNavigationTimeout change selector waits?

No. It covers navigation methods. Use setDefaultTimeout or a per-call timeout for general waits.

Why does a page work manually but time out in Puppeteer?

Automation may have a different viewport, user agent, authentication state, permissions, timing, or network path. Log the final URL and page errors, and capture the rendered state at the failure point.

What version should I check?

Match the examples to the Puppeteer version installed in your project. The cited API pages identify version 25.11.0, and API details can change.