“Failed to launch the browser process” is a wrapper, not a diagnosis. The useful error is usually in Chromium’s stderr immediately below it. Capture the complete output, then identify whether the executable is missing, a shared library cannot load, permissions or sandbox policy blocked startup, or a browser/package change introduced a regression. Your Puppeteer version, browser version, operating system or base image, configured executable path, and runtime type (local, CI, Docker, or hosted) determine the correct fix.
Start with a diagnostic record
Before changing launch flags or downgrading anything, save the facts that make the failure reproducible:
- The complete terminal or CI log, including Chromium stderr beneath the generic message.
- Puppeteer version and the browser version it is trying to start.
- Operating system, CPU architecture, and—if applicable—the exact Docker base image.
- Your
executablePath, Puppeteer cache settings, and the code that callspuppeteer.launch(). - Whether the same code works on a developer workstation but fails in CI, Docker, or a hosted runtime.
Do not assume this is a Puppeteer defect. The wrapper is emitted when the child browser exits before connecting; the browser’s own message normally identifies the environmental cause.
Read Chromium’s first specific stderr message
Run your script with all output captured and look for the first concrete line after “Failed to launch the browser process.” Preserve literal phrases because they point to different branches:
Recommended Free Tools
#1 Best Overall
- “Could not find expected browser locally” or a path such as
ENOENT: the browser was not downloaded, was removed from the image, or the configured path is wrong. - “error while loading shared libraries”, often naming
libnss3.so: the binary exists but the runtime lacks a shared dependency. - Messages about sandbox initialization, permissions, read-only filesystems, or inability to create a profile: the process can see the binary but cannot perform a required operation.
- A clean browser exit with no missing-file message immediately after a Puppeteer or Chromium upgrade: investigate a version pairing or policy regression.
A Puppeteer issue report, for example, shows Linux stderr naming missing libnss3.so; the generic wrapper alone would not reveal that.
Verify the browser installation and path
Check what Puppeteer downloaded
Since Puppeteer v19.0.0, downloaded browsers are placed under ~/.cache/puppeteer by default. In the same account and runtime that runs your application, inspect that directory and confirm that the expected Chrome or Chromium executable exists. A container build may download it as root while the application runs as an unprivileged user, making the apparent installation invisible or inaccessible.
If your project intentionally uses a system browser, set and test an explicit path:
const browser = await puppeteer.launch({ executablePath: '/usr/bin/google-chrome' });Use the path inside the target container or CI worker, not the path from your laptop. Remove stale paths from environment variables and deployment secrets, and verify that the file is executable.
Repair blocked or skipped install scripts
Package managers and CI security settings sometimes prevent Puppeteer’s post-install download. Install the browser explicitly in the environment where the job will run:
npx puppeteer browsers installAfter changing Puppeteer configuration, reinstall Puppeteer so the configuration is applied to the download process. Cache the resulting browser directory in CI only when the cache key includes the operating system, architecture, Puppeteer version, and browser revision; otherwise a cache from another image can produce misleading failures.
Relocate the cache when the default directory is unsuitable
Set PUPPETEER_CACHE_DIR to a writable, persistent location when home directories are ephemeral or read-only. Make the variable available during installation and at runtime, and grant the application user read and execute access to the entire path. A configuration change made only after the browser was downloaded does not move an existing binary automatically.
Diagnose Linux shared-library failures
Test the exact browser binary inside the same image or virtual machine that will launch it. The Puppeteer troubleshooting documentation recommends:
Free tools Windows power users keep installed
One-click scans. No signup required.
ldd /path/to/chrome | grep notAny line ending in not found is a missing loader dependency. Common Debian or Ubuntu requirements include libnss3, libatk1.0-0, libgbm1, libasound2, libgtk-3-0, and related graphics, font, X11, and accessibility libraries. Exact package names differ by distribution and release. Use the current dependency list declared by the Chrome installer for your base image rather than copying a command written for another distribution.
Check architecture as well as libraries. An x86_64 browser in an ARM runtime, or a binary requiring a loader absent from a minimal image, can fail before Chromium prints a helpful message. Run file /path/to/chrome, confirm the image architecture, and repeat ldd in the final production stage—not only in a build stage.
Check permissions, sandbox, and operating-system policy
Filesystem and user permissions
- Ensure the application user can traverse every parent directory, execute the browser, read its libraries, and write a temporary profile directory.
- Confirm that
/tmpor your configured temporary directory is writable and has sufficient space. - In a read-only container, provide a writable home, cache, and profile directory instead of expecting Chrome to create them.
- On Linux, inspect ownership and mode bits for downloaded sandbox files. Puppeteer v22.14.0 and later attempts to set permissions for downloaded Chrome sandbox files; older versions or continuing errors may require a manual permission check.
Windows enterprise Chrome policies
Chrome on Windows can fail when an enterprise policy requires extensions. Puppeteer disables extensions by default, so that policy can prevent startup. The documented option for this case is:
const browser = await puppeteer.launch({ enableExtensions: true });Use this only when the policy is the actual stderr diagnosis. It is not a general launch setting.
Do not make --no-sandbox the default fix
Disabling Chromium’s sandbox changes a security boundary. The available guidance does not establish that it is generally safe or necessary. First correct the user, filesystem, sandbox-file permissions, container policy, and required kernel capabilities. If your security team approves a sandbox change for a specific isolated runtime, document the risk and scope it to that deployment rather than adding the flag blindly to application code.
Investigate Puppeteer and Chromium version changes
Record both versions, because Puppeteer and the browser revision it launches are a pair. Compare a failing build with the last known-good build and identify which component changed. Reproduce with a minimal script in the same image before changing several variables at once.
Puppeteer issue #13365 describes one Docker setup using Puppeteer 23.9.0 and Chromium 131 that failed until Chromium 130 was used. That is a dated, individual report—not a universal instruction to downgrade Chromium. Treat a rollback as a temporary isolation experiment, then move to a supported current pairing once the regression is understood. Pin versions deliberately in CI and test upgrades in the production base image.
A repeatable troubleshooting procedure
- Collect the full log. Enable CI log retention and copy Chromium stderr, not just the final Puppeteer exception.
- Classify the first specific line. Choose missing browser, missing library, permission or policy, or version regression.
- Verify the runtime. Check OS, architecture, user, base image, executable path, cache directory, and writeable temporary storage inside the failing environment.
- Repair one layer. Install the browser, correct the path, add the distribution-appropriate library, fix ownership, or address the identified policy.
- Run a minimal launch test. Use one page and no application plugins so the result isolates browser startup.
- Compare versions. If the failure began after an upgrade, test the previous known-good pair and consult current version-specific documentation before pinning.
- Promote the fix. Rebuild the final image, run the same test as the production user, and keep the diagnostic command in your deployment checklist.
Common symptoms and targeted fixes
| Symptom | Likely cause | Action |
|---|---|---|
| “Could not find expected browser locally” | Download skipped, cache moved, or wrong executable path | Run npx puppeteer browsers install, inspect ~/.cache/puppeteer or PUPPETEER_CACHE_DIR, and set a path that exists in the target runtime. |
| “error while loading shared libraries: libnss3.so” | Missing Linux runtime dependency | Run ldd in the final image and install the package matching that distribution. |
| Browser starts locally but not in Docker | Different libraries, user, architecture, filesystem, or sandbox policy | Reproduce inside the container as the production user; do not copy host paths or packages. |
| Windows launch fails only on a managed machine | Enterprise extension policy conflicts with disabled extensions | Confirm the policy and use enableExtensions: true only for that case. |
| Failure begins after a browser upgrade | Version-specific regression or unsupported pairing | Compare the last working pair, isolate the changed component, and pin temporarily while validating a supported update. |
When a hosted browser is the better deployment boundary
If your environment cannot provide the required libraries, writable profile storage, or browser permissions, a hosted capture service avoids maintaining a local Chromium runtime. This is a deployment choice, not a repair to Puppeteer’s installation; keep it separate from your root-cause record and security review.
Best Value
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One request returns a PNG, JPEG, WebP, or PDF without installing Chromium in your application. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status.
For a direct request, see the ScreenshotNeo documentation:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The API also supports full-page and element captures, device presets, custom viewports, retina scale, PDF paper and page-range controls, custom CSS or JavaScript, clicks, selector or network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to make your first request.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →How to decide between local Puppeteer and a hosted capture
- Keep Puppeteer local when you need browser automation, authenticated sessions, custom debugging, or control over the exact runtime and security policy.
- Use a hosted capture when the main output is a screenshot or PDF and maintaining browser binaries and Linux dependencies is the operational problem.
- Use a hybrid when interactive tests run locally but documentation, previews, or bulk public-page images can be delegated to an API.
Whichever route you choose, retain the original stderr and version record. That evidence distinguishes a missing dependency from a policy decision and prevents a risky launch flag from becoming a permanent workaround.
Frequently Asked Questions
Does reinstalling Puppeteer always fix this error?
No. Reinstallation helps when the browser download was skipped or corrupted. Missing shared libraries, permissions, enterprise policies, and browser regressions require their corresponding fixes.
Where should I run the ldd check?
Run it against the exact browser executable inside the final CI worker, container image, or hosted runtime and as close as possible to the user that launches Puppeteer.
Should I permanently pin Chromium 130?
No. The Chromium 130 result comes from one dated issue report. Compare your own versions and use a pin only as a controlled regression workaround while validating a supported pairing.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
