"Failed to launch the browser process" is the outer wrapper of half a dozen different problems. Puppeteer prints it whenever Chrome exits before it is ready, and puts the real reason a few lines lower, in Chrome's own stderr. "Could not find Chrome" is its sibling, printed before Puppeteer even tries. This page reproduces each one we know of — on WSL2 and in Docker — with the exact text Puppeteer 25.7 printed and the fix that made Chrome start.
How we tested. On 2026-11-21, Puppeteer 25.7.0, which expects Chrome for Testing 152.0.7977.42, on Node.js 20 in WSL2 (Ubuntu) and in two Docker images: node:24-slim and the official ghcr.io/puppeteer/puppeteer:25.7.0. The script was a bare puppeteer.launch() that prints the error. We did not test Windows, macOS, AWS Lambda or Vercel; the notes on those below are pointers, not measurements.
Find the real message first
In Puppeteer 25.7 the wrapper reads "Failed to launch the browser process:" with a colon; older versions printed "Failed to launch the browser process!". The line that matters is under stderr::
Error: Failed to launch the browser process: Code: 127
stderr:
/pc/chrome/linux-152.0.7977.42/chrome-linux64/chrome: error while loading shared libraries: libglib-2.0.so.0: cannot open shared object file: No such file or directory
TROUBLESHOOTING: https://pptr.dev/troubleshooting
If your logs only keep the first line, log error.message in full. Then find your case:
What stderr (or the error) says |
Cause | Section |
|---|---|---|
Could not find Chrome (ver. 152.0.7977.42) |
the browser is not in the cache Puppeteer reads | 1 |
Browser was not found at the configured executablePath (…) |
a wrong executablePath |
2 |
error while loading shared libraries: libglib-2.0.so.0 (or libnss3.so, libatk-1.0.so.0…) |
missing system libraries | 3 |
Running as root without --no-sandbox is not supported |
Chrome as root | 4 |
No usable sandbox! |
no working sandbox | 5 |
The browser is already running for …/profile |
a userDataDir in use |
6 |
1. "Could not find Chrome (ver. …)"
Error: Could not find Chrome (ver. 152.0.7977.42). This can occur if either
1. you did not perform an installation before running the script (e.g. `npx puppeteer browsers install chrome`) or
2. your cache path is incorrectly configured (which is: /root/.cache/puppeteer).
For (2), check out our guide on configuring puppeteer at https://pptr.dev/guides/configuration.
Puppeteer looks for one exact Chrome build in one directory: ~/.cache/puppeteer of the user running the script, or PUPPETEER_CACHE_DIR. The message prints both the version and the path, and four things gave us this error:
- The install script did not run.
npm i puppeteer --ignore-scriptsinstalls the package without the browser. Package managers that block dependency install scripts (pnpm 10 does unless a package is allowed to build) do the same, andPUPPETEER_SKIP_DOWNLOAD=trueskips it on purpose. - A different user, a different home. The browser was downloaded as one user and the script runs as another. In the official image, run with
-u root, the cache path became/root/.cache/puppeteer, empty, while Chrome sat in/home/pptruser/.cache/puppeteer. The same happens withsudo, a systemd service with its own user, or a web server running aswww-data. - A different cache directory.
PUPPETEER_CACHE_DIRset at install time but not at run time, or the other way round, or a Docker multi-stage build that copiesnode_modulesbut not the cache. - The wrong version. After upgrading Puppeteer, a cache holding only Chrome 143 still gave "Could not find Chrome (ver. 152.0.7977.42)". Every Puppeteer release pins its own Chrome.
The fix, run as the same user and with the same environment as the script:
npx puppeteer browsers install chrome
# chrome@152.0.7977.42 /…/cache/chrome/linux-152.0.7977.42/chrome-linux64/chrome
After that the same script launched Chrome/152.0.7977.42. In Docker, run it in the final stage after npm ci, or set PUPPETEER_CACHE_DIR to a path inside the app directory so the browser travels with it; Puppeteer's configuration guide also lets you put cacheDirectory in a .puppeteerrc.cjs.
2. "Browser was not found at the configured executablePath"
Error: Browser was not found at the configured executablePath (/usr/bin/google-chrome)
You passed executablePath (or PUPPETEER_EXECUTABLE_PATH) and nothing is there. Common with puppeteer-core, which never downloads a browser. Check with ls -l and which chromium chromium-browser google-chrome; distributions name the binary differently. If you point Puppeteer at a system Chrome, keep in mind that each Puppeteer release is tested against one Chrome version.
3. Missing shared libraries
The example at the top: Chrome is found, the operating system cannot load it. We got it by running Puppeteer's own Chrome in node:24-slim, which has no graphics libraries. On Debian and Ubuntu, as root:
npx puppeteer browsers install chrome --install-deps
--install-deps installs the packages with apt. To see what is missing, Puppeteer's troubleshooting guide suggests ldd chrome | grep not. In a Dockerfile, run apt-get update in the same layer before it; running Puppeteer in Docker has the three errors we hit building a slim image and a Dockerfile that works. On Alpine, Puppeteer's guide notes that Chrome "does not support Alpine out of the box" and shows the distribution's chromium package used with executablePath.
4. "Running as root without --no-sandbox is not supported"
Error: Failed to launch the browser process: Code: 1
stderr:
[…:ERROR:content/browser/zygote_host/zygote_host_impl_linux.cc:102] Running as root without --no-sandbox is not supported. See https://crbug.com/638180.
We got it in the official image run with -u root. Containers run as root unless the image says otherwise, so this is the usual first error in a home-made Dockerfile. The right fix is a non-root user:
RUN useradd --create-home pptr
USER pptr
RUN npx puppeteer browsers install chrome # as this user, so the cache is in its home
args: ['--no-sandbox'] also made Chrome start as root in our test. Puppeteer's guide calls running without a sandbox "strongly discouraged" and says to use it only if you "absolutely trust" the content you open: a screenshot service that loads arbitrary URLs does not.
5. "No usable sandbox!"
[…:FATAL:content/browser/zygote_host/zygote_host_impl_linux.cc:129] No usable sandbox! If you are running on Ubuntu 23.10+ or another Linux distro that has disabled unprivileged user namespaces with AppArmor, see https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md. …
Chrome runs as a normal user but cannot create its sandbox. In our test the official image without extra flags gave it; docker run --cap-add=SYS_ADMIN made it start, as Puppeteer's Docker guide says the image requires. Outside Docker, the troubleshooting guide names an AppArmor profile on Ubuntu 23.10+ that "prevents Chrome for Testing binaries downloaded by Puppeteer from using user namespaces"; the Chromium link in the message lists the workarounds. We did not reproduce the AppArmor case.
6. "The browser is already running for …"
Error: The browser is already running for /…/profile. Use a different `userDataDir` or stop the running browser first.
Two launches with the same userDataDir: a second worker, a test run in parallel, or a Chrome left over from a crashed run that still holds the profile. Give each process its own directory, or close the old browser; after a hard kill, a stale SingletonLock file in the profile can keep the lock.
Serverless, Windows and the rest
We did not run these, so only pointers:
- AWS Lambda, Vercel and other functions cannot run the full Chrome for Testing download. The usual setup is
puppeteer-corewith a Chromium build packaged for Lambda, such as@sparticuz/chromium, and itsexecutablePath(); Vercel's own guide uses@sparticuz/chromium-minto stay under its function size limit. Check that the Chromium build matches yourpuppeteer-coreversion. - Windows: Puppeteer's troubleshooting guide notes that it passes
--disable-extensionsby default, which fails under some Chrome policies;ignoreDefaultArgs: ['--disable-extensions']is the workaround it gives. - A crash after launch ("Target closed" on the first page) is a different problem, usually memory: see Protocol error: Target closed.
When you only need screenshots
If the browser is only there to take screenshots of public pages, a screenshot API removes the install, the sandbox and the libraries from your servers: one HTTP request returns the image. A viewport screenshot is 1 render of the quota, a full page 2 (pricing). For logged-in pages, PDFs of your own HTML or anything interactive, fix the launch with the steps above and keep Puppeteer.