Puppeteer errors, explained one by one

30 seconds for navigations and for waits such as waitForSelector, waitForFunction and locator actions. Change it globally with page.setDefaultTimeout(ms) and page.setDefaultNavigationTimeout(ms), or per call with the timeout option. Passing 0 disables the timeout, which is rarely a good idea in production because a stuck page will then hang the script forever.

Import TimeoutError from puppeteer and check err instanceof TimeoutError in your catch block. That separates slow pages, which may be worth retrying, from real failures such as missing selectors, DNS errors or a crashed browser. In current versions, inspect err.cause on wait errors for the underlying timeout detail.

Only for pages that truly go quiet. networkidle0 waits until there have been no network connections for 500 ms, which never happens on sites with analytics beacons, websockets or polling, so navigations time out. Navigating with domcontentloaded and then waiting for a specific selector is faster and more reliable for most scraping and testing.

page.locator(selector) returns a locator whose actions, such as click and fill, wait for the element to be attached, visible, enabled and stable before acting, and re-query the page each time. It avoids No element found for selector, most detached-node errors and many not-clickable errors that come from acting on elements too early.

Containers usually lack Chrome's system libraries, run as root, and have only 64 MB of /dev/shm. Those produce Failed to launch the browser process and Target closed errors. Use an image built for headless Chrome, run as a non-root user, and add --shm-size=1gb or the --disable-dev-shm-usage flag.

It disables Chrome's process sandbox, which protects the host from malicious page content. It is acceptable when you control the pages being loaded and the container is already isolated, but it is risky for crawling arbitrary sites. Running Chrome as a non-root user usually makes the flag unnecessary.

Into a cache directory, ~/.cache/puppeteer by default, during npm install. Each Puppeteer version expects one specific Chrome for Testing build. You can change the location with a .puppeteerrc.cjs file or the PUPPETEER_CACHE_DIR environment variable, and install manually with npx puppeteer browsers install chrome.

An ElementHandle points to one DOM node. Modern frameworks replace nodes when they re-render, and navigations destroy them entirely, so stored handles become detached. Query elements just before using them, extract plain values instead of passing handles around, and prefer locators, which re-resolve the selector on every action.