Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →“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 browser executable is missing, a shared library cannot load, a sandbox or permission policy blocked startup, or a particular browser/package version regressed in your runtime.
Before changing flags or downgrading anything, record your Puppeteer version, browser version, operating system and base image, configured executablePath, CPU architecture, and whether the failure occurs locally, in CI, in Docker, or in a hosted runtime. The same top-level message can have completely different fixes.
Start with the complete launch output
Run the smallest possible launch and preserve every line written to stderr. Do not report only the final Puppeteer exception. The first specific browser message is the key evidence.
const puppeteer = require('puppeteer');
(async () => {
try {
const browser = await puppeteer.launch({
headless: true,
dumpio: true
});
await browser.close();
} catch (error) {
console.error(error.stack || error);
process.exitCode = 1;
}
})();Collect this information with the output:
- Puppeteer package version (
npm ls puppeteer). - Browser version and whether Puppeteer downloaded it or you supplied
executablePath. - Operating system, distribution, base image, and CPU architecture.
- Node.js version and the exact launch options.
- Whether the same code works outside the failing environment.
Keep the literal phrases “Could not find expected browser locally” and “error while loading shared libraries” when they appear; they point to different branches of the diagnosis.
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 →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Follow the failure signature
Missing executable or wrong path
If stderr says the expected browser cannot be found, verify that a browser exists in the same runtime as your Node process. A browser installed on your laptop is irrelevant to a container or CI worker. Print the configured path and test it:
node -e "const p=require('puppeteer'); console.log(p.executablePath())"
ls -l /path/from-the-commandPuppeteer downloads browsers under ~/.cache/puppeteer by default from version 19.0.0 onward. In a build system, that home directory may be ephemeral or owned by a different user. Set PUPPETEER_CACHE_DIR to a persistent, writable location when appropriate.
Package-manager install scripts can also be disabled by CI policy. In that case, install the browser explicitly:
npx puppeteer browsers installAfter changing Puppeteer configuration, reinstall Puppeteer so the new configuration is applied. In production images, perform the browser installation during the image build and verify the resulting cache path in the final image.
“error while loading shared libraries” on Linux
A Linux browser can exist and still fail before opening a window because its dynamic loader cannot find a required library. Test the binary inside the exact image or container that runs your application:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
ldd /path/to/chrome | grep notTypical Debian or Ubuntu dependencies include libnss3, libatk1.0-0, libgbm1, libasound2, and libgtk-3-0, plus related libraries. Names and availability vary by distribution and release. Use the dependency list for your current Chrome installer and your base image rather than copying a package command written for another distribution. A missing libnss3.so, for example, is an operating-system dependency failure, not a Puppeteer API failure.
Sandbox, ownership, and filesystem permissions
Sandbox errors often occur when the browser runs as a different user, in a restricted container, or with a read-only or non-executable filesystem. Check that the executable, its parent directories, the cache, and temporary directories are readable and executable by the runtime user. Confirm that the Chrome sandbox file has the permissions expected by your browser build.
Puppeteer 22.14.0 and later attempts to set permissions for downloaded Chrome sandbox files. Older versions, copied browser directories, or custom images may still require a manual permissions check. Do not treat --no-sandbox as a universal repair: disabling sandboxing changes your security boundary and may be prohibited by your deployment policy. First determine exactly which permission or sandbox message is reported, then choose a fix that your security team accepts.
Windows enterprise policy and extensions
On Windows, enterprise Chrome policies that require extensions can conflict with Puppeteer because Puppeteer disables extensions by default. If the stderr output and policy configuration match that case, enable extensions explicitly:
const browser = await puppeteer.launch({
enableExtensions: true
});Apply this only when the policy requires it. Enabling extensions unnecessarily adds another variable to startup.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Browser/package regression
Compare the Puppeteer and browser versions with the last known working build. A reported Docker incident involving Puppeteer 23.9.0 and Chromium 131 stopped failing when that individual setup used Chromium 130. That is a dated, environment-specific report, not evidence that everyone should downgrade Chromium.
Use a rollback only as a controlled experiment: reproduce with the previous pair, record the result, and then inspect the release change or update your base image. Compare operating system, architecture, launch flags, and libraries before attributing the failure to a version. Pin a compatible pair temporarily if necessary, but schedule removal of the pin after a current compatibility check.
Free tools Windows power users keep installed
One-click scans. No signup required.
Verify Puppeteer’s browser installation
Inspect the cache and executable
- Run
npm ls puppeteerand record the exact version. - Print Puppeteer’s resolved executable path.
- List that path and run its
--versioncommand as the production user. - Check that
PUPPETEER_CACHE_DIR, if set, is identical during installation and execution. - Confirm that your deployment artifact actually contains the cache; multi-stage builds often leave it behind.
If the path points to a location that does not exist, install the managed browser explicitly with npx puppeteer browsers install, or set executablePath to a browser installed in the image. Avoid mixing an old system Chromium with a newly installed Puppeteer until you have tested that pairing.
Use an explicit path only when you own it
const browser = await puppeteer.launch({
executablePath: process.env.CHROME_BIN,
headless: true
});Set CHROME_BIN in the runtime and validate it before launch. An explicit path makes deployments reproducible, but it also makes a stale path an immediate failure. If you rely on Puppeteer’s managed browser, omit the option and keep its cache available.
Linux container and CI checklist
- Use the same base image for dependency installation and execution.
- Run
lddand the browser’s--versioninside the final image, not on the host. - Ensure the runtime user can read the browser, cache, fonts, temporary directory, and shared libraries.
- Preserve the Puppeteer cache between build and run stages, or install it in the final stage.
- Check whether CI blocks npm lifecycle scripts; run the documented browser installation command explicitly when it does.
- Record architecture (for example, x86_64 versus ARM64) and use a browser build that supports it.
- Review container security profiles, read-only mounts, and seccomp restrictions when stderr identifies a sandbox or syscall denial.
Installing random packages until launch succeeds can produce a fragile image. Start with the first missing library reported by the loader, then repeat the check until no unresolved dependencies remain.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
A minimal diagnostic launch
This script prints versions, uses browser stderr, and closes cleanly. Run it in the failing environment:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallconst puppeteer = require('puppeteer');
(async function () {
console.log('Puppeteer:', require('puppeteer/package.json').version);
console.log('Executable:', puppeteer.executablePath());
try {
const browser = await puppeteer.launch({
headless: true,
dumpio: true,
timeout: 30000
});
const page = await browser.newPage();
await page.goto('about:blank');
console.log('Browser:', await browser.version());
await browser.close();
} catch (err) {
console.error('Launch failed:', err.stack || err);
process.exitCode = 1;
}
})();If this fails, adding application pages, proxies, authentication, or complex flags will obscure the cause. Fix the baseline first, then reintroduce your normal options one at a time.
Common symptoms and targeted fixes
| Observed message or symptom | Most likely branch | Next action |
|---|---|---|
| Could not find expected browser locally | Browser was not downloaded, cache is missing, or path is wrong | Inspect puppeteer.executablePath(), cache location, and run npx puppeteer browsers install |
| error while loading shared libraries | Linux dependency absent from the runtime | Run ldd browser | grep not; install the missing dependency for your distribution |
| Sandbox or permission denied | User, filesystem, sandbox file, or container policy | Check ownership, executable bits, mounts, and security policy; do not blindly disable the sandbox |
| Works locally, fails in CI or Docker | Different image, user, architecture, cache, or install-script policy | Run the browser binary and dependency checks inside the failing artifact |
| Started failing after a browser update | Version-specific regression or changed dependency | Compare the last working pair and test a controlled pin |
| Windows launch blocked by required extensions | Enterprise Chrome policy conflicts with default extension disabling | Use enableExtensions: true only for that policy scenario |
Reliability and deployment decisions
A local browser gives you control over binaries, libraries, fonts, network access, and data residency, but you must maintain every runtime dependency. A hosted browser can remove image and sandbox maintenance, yet introduces network latency, credentials, vendor limits, and a separate failure surface. Decide after identifying the actual failure signature, security constraints, architecture, and whether the workload is local, containerized, CI-based, or hosted. There is no safe universal launch flag or downgrade.
For repeatable builds, pin the Node, Puppeteer, browser, and base-image versions together; run the diagnostic launch as a deployment health check; and retain stderr in CI logs. When upgrading, change one layer at a time so a regression can be isolated.
Or skip the browser setup
If your goal is a reliable website image rather than maintaining Chromium, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. 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, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
cURL:
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}`);See the complete parameter list and response behavior in the ScreenshotNeo documentation. Its 63 options include full-page lazy-image capture, CSS-element capture, device presets, retina scale, PDF paper and page ranges, custom CSS or JavaScript, clicks, 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. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Create a free ScreenshotNeo account to try it without a card.
FAQ
Is this always a Puppeteer bug?
No. The message is a generic wrapper. The browser’s stderr commonly identifies an installation, dependency, policy, permission, or version problem in the runtime.
Should I always add --no-sandbox?
No. It can weaken isolation and may violate deployment requirements. Use it only when a diagnosed environment constraint and an accepted security design require it.
Recommended Free Tools
Why does a browser installed on my machine not help Docker?
Docker runs its own filesystem, libraries, user, and architecture. The executable and every dependency must be present in the image that launches it.
When is a browser rollback justified?
Only after reproducing a regression with a controlled comparison of the previously working Puppeteer/browser pair and the current runtime. A single issue report is not a general compatibility policy.
Frequently Asked Questions
How do I capture the real Chromium error?
Launch with Puppeteer’s dumpio: true option and preserve all stderr lines; diagnose the first specific message beneath the wrapper exception.
Where does Puppeteer store downloaded browsers?
Since Puppeteer 19.0.0, the default location is ~/.cache/puppeteer; set PUPPETEER_CACHE_DIR when you need another writable or persistent location.
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.
