Puppeteer: Failed to launch the browser process
Last verified
Error: Failed to launch the browser process: Code: 127
stderr:
/home/user/.cache/puppeteer/chrome/linux-142.0.7444.59/chrome-linux64/chrome: error while loading shared libraries: libnss3.so: cannot open shared object file: No such file or directory
TROUBLESHOOTING: https://pptr.dev/troubleshootingWhat it means
Puppeteer found the Chrome binary and started it, but the process exited (or failed to spawn) before it opened the DevTools connection. The headline is generic; the real reason is in the stderr section that Puppeteer copies from Chrome. Older versions printed Failed to launch the browser process! with an exclamation mark, and the same diagnosis applies.
On Linux the stderr almost always matches one of a few patterns: error while loading shared libraries: ... cannot open shared object file (missing OS packages), Running as root without --no-sandbox is not supported (Docker running as root), No usable sandbox! (kernel or container blocks the sandbox), or a missing display when launching headful. On Windows and macOS it is more often antivirus, permissions, or a quarantined binary.
What is not wrong: your page code. Nothing has run yet.
What it looks like
# Debian/Ubuntu: common libraries for Chrome
apt-get update && apt-get install -y \
ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
libgbm1 libgtk-3-0 libnss3 libxss1 libxshmfence1
// Node.js: launch as a non-root user where possible
const browser = await puppeteer.launch({
args: process.getuid?.() === 0 ? ['--no-sandbox'] : [],
});Why it happens
- Missing system libraries such as libnss3, libatk-bridge2.0-0, libgbm1 or libasound2 on slim Linux images.
- Running as root in a container, which Chrome refuses without --no-sandbox.
- The container or kernel does not permit user namespaces, so the sandbox cannot start.
- Launching with headless: false on a server with no display server.
- A wrong executablePath pointing to a non-Chrome binary or a binary for another architecture.
How to fix it
- Read the stderr lines below the headline; they name the actual failure.
- For missing libraries, install the packages listed in Puppeteer's troubleshooting guide, or use the official ghcr.io/puppeteer/puppeteer image.
- In Docker, run as a non-root user; if that is impossible and the content is trusted, pass args: ['--no-sandbox'].
- For headful runs on servers, use headless mode or a virtual display such as xvfb-run.
- Verify the binary runs on its own: execute it with --version from the same environment.
How to stop it recurring
Build automation containers from an image designed for headless Chrome, and run them as a non-root user so the sandbox stays on. Add a startup smoke test that launches and closes the browser, so environment problems fail the deploy instead of the first real job. Keep architecture in mind on ARM machines.
Official documentation: pptr.dev/troubleshooting. See all Puppeteer error messages.
Related errors
Definitions
- PuppeteerPuppeteer is Google's open-source Node.js library for controlling Chrome and Firefox. It drives Chrome over th
- Chrome DevTools Protocol (CDP)The Chrome DevTools Protocol (CDP) is the JSON-over-WebSocket interface Chrome exposes for inspecting and cont
- CSS SelectorA CSS selector is a pattern used to identify and target specific HTML elements on a web page, widely used in b
- Headless ChromeHeadless Chrome is Google Chrome running without a visible window. It renders pages and runs JavaScript like n
- IframeAn iframe (inline frame) is an HTML element that embeds a separate web page within a parent page, creating an
- Web ElementA web element is any individual component rendered on a web page — buttons, links, input fields, images, text
Quick answers
What does "Failed to launch the browser process" mean in Puppeteer?
Puppeteer found the Chrome binary and started it, but the process exited (or failed to spawn) before it opened the DevTools connection. The headline is generic; the real reason is in the stderr section that Puppeteer copies from Chrome. Older versions printed Failed to launch the browser process! with an exclamation mark, and the same diagnosis applies.
How do I fix "Failed to launch the browser process"?
1. Read the stderr lines below the headline; they name the actual failure. 2. For missing libraries, install the packages listed in Puppeteer's troubleshooting guide, or use the official ghcr.io/puppeteer/puppeteer image. 3. In Docker, run as a non-root user; if that is impossible and the content is trusted, pass args: ['--no-sandbox']. 4. For headful runs on servers, use headless mode or a virtual display such as xvfb-run. 5. Verify the binary runs on its own: execute it with --version from the same environment.
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.