{"id":10412,"library":"puppeteer","title":"Puppeteer: Headless Browser Automation","description":"Puppeteer provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi, enabling browser automation for tasks like testing, scraping, and PDF generation. It runs headless by default but can be configured for full UI. The current stable version is 24.41.0. Releases are frequent, often several times a month, typically synchronizing with new Chrome and Firefox browser versions.","status":"active","version":"24.41.0","language":"javascript","source_language":"en","source_url":"https://github.com/puppeteer/puppeteer#main","tags":["javascript","puppeteer","chrome","headless","automation","typescript"],"install":[{"cmd":"npm install puppeteer","lang":"bash","label":"npm"},{"cmd":"yarn add puppeteer","lang":"bash","label":"yarn"},{"cmd":"pnpm add puppeteer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is preferred, but CommonJS is also supported.","wrong":"const puppeteer = require('puppeteer');","symbol":"puppeteer","correct":"import puppeteer from 'puppeteer';"}],"quickstart":{"code":"import puppeteer from 'puppeteer';\n\n(async () => {\n  const browser = await puppeteer.launch();\n  const page = await browser.newPage();\n\n  await page.goto('https://developer.chrome.com/');\n\n  await page.setViewport({width: 1080, height: 1024});\n\n  await page.keyboard.press('/');\n\n  await page.locator('::-p-aria(Search)').fill('automate beyond recorder');\n\n  await page.locator('.devsite-result-item-link').click();\n\n  const textSelector = await page\n    .locator('::-p-text(Customize and automate)')\n    .waitHandle();\n  const fullTitle = await textSelector?.evaluate(el => el.textContent);\n\n  console.log('The title of this blog post is \"%s\".', fullTitle);\n\n  await browser.close();\n})();","lang":"typescript","description":"This example launches a headless Chrome browser, navigates to a URL, interacts with elements using Puppeteer's custom selectors, extracts text content, and then closes the browser."},"warnings":[{"fix":"Install `puppeteer-core` instead: `npm i puppeteer-core`. You will then need to provide the `executablePath` option to `puppeteer.launch()`.","message":"The default `puppeteer` package automatically downloads a compatible Chromium browser, which can significantly increase installation time and disk space. For smaller installations or to use an existing browser, consider `puppeteer-core`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 18 or newer. Use a Node.js version manager like nvm (Node Version Manager) for easy switching.","message":"Puppeteer requires Node.js version 18 or higher. Using an older Node.js version will result in installation or runtime errors.","severity":"breaking","affected_versions":">=20.0.0"},{"fix":"Add `--no-sandbox` to the `args` array in `puppeteer.launch()`: `puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })`. For production, investigate a more secure sandboxing configuration for your environment.","message":"When running Puppeteer in environments like Docker containers or CI/CD pipelines, you may encounter errors related to sandboxing. Disabling the sandbox with `--no-sandbox` is often necessary but introduces security risks.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly update your Puppeteer package (`npm update puppeteer`) to ensure compatibility with the browser it launches. If using `puppeteer-core` with an external browser, ensure that browser is also up-to-date.","message":"Puppeteer frequently updates to support the latest Chrome/Firefox versions. Mismatches between your installed Puppeteer version and the browser it controls can lead to unexpected behavior or broken features due to DevTools Protocol changes.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"While powerful, consider supplementing custom selectors with standard CSS selectors (`page.locator('div.my-class')`) or `page.$eval()` for robust and widely understood element selection, especially for stable UI components.","message":"Puppeteer's custom selectors like `::-p-aria()`, `::-p-text()`, and `::-p-xpath()` offer powerful ways to locate elements but are not standard CSS or XPath. Relying heavily on them may make your tests less portable outside Puppeteer.","severity":"gotcha","affected_versions":">=13.0.0"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"If using `puppeteer`, try reinstalling it to redownload the browser (`npm install puppeteer`). If using `puppeteer-core`, you must specify the `executablePath` in `puppeteer.launch()` to point to your browser binary.","cause":"Puppeteer could not find a Chrome/Chromium executable at the expected path. This often happens if `puppeteer-core` is used without `executablePath`, or the `puppeteer` installation failed to download the browser.","error":"Error: Failed to launch the browser process! No browser found at..."},{"fix":"Ensure that `browser.close()` or `page.close()` is called only after all necessary operations on that context are complete. Check for asynchronous operations that might complete after a page or browser is closed.","cause":"You attempted to interact with a browser, page, or frame that has already been closed or navigated away from, invalidating the context.","error":"Error: browserContext.newPage: Target closed."},{"fix":"Increase the timeout for the specific navigation call (`await page.goto(url, { timeout: 60000 });`) or globally (`page.setDefaultNavigationTimeout(60000);`). Ensure the network and server are responsive.","cause":"A navigation action (`page.goto()`, `page.click()` followed by navigation, etc.) took longer than the default 30-second timeout.","error":"Error: Navigation timeout of 30000 ms exceeded"},{"fix":"After any significant page navigation or DOM manipulation, re-select elements and obtain new `ElementHandle`s rather than reusing old ones. Ensure your element references are always fresh.","cause":"This usually indicates that an `ElementHandle` or another browser-side object is being used after the page has reloaded, navigated, or the element itself no longer exists in the DOM.","error":"Error: function: Cannot find context with specified id"},{"fix":"Upgrade your Node.js version to 18 or higher. You can use tools like `nvm install 18` and `nvm use 18`.","cause":"Your current Node.js version is older than the minimum required by Puppeteer.","error":"Error: The 'engines' field in 'package.json' specifies that this package is compatible only with Node.js >=18."}],"ecosystem":"npm"}