Recommended Free Tools
Start by identifying which layer failed: package installation, browser download, browser discovery, operating-system dependencies, or Chrome launch. A missing-browser error calls for a different fix than a browser that is found but cannot start. Before changing anything, record the full error and stderr, Puppeteer and Node.js versions, operating system and architecture, package manager, and whether the project uses puppeteer or puppeteer-core.
Identify the failure layer first
Puppeteer’s error messages are clues, not diagnoses. “Could not find expected browser locally” and “Could not find Chrome (ver. …).” usually point toward installation, browser selection, or cache location. “Failed to launch chrome!” and “No usable sandbox!” indicate that the browser launch path needs investigation, but neither phrase by itself establishes the root cause.
Capture these details before applying a fix:
- The complete error, stack trace, and browser stderr—not just “Puppeteer does not work.”
- The installed Puppeteer package and version, Node.js version, operating system, and CPU architecture.
- The package manager and whether install scripts were allowed to run.
- Whether the code imports
puppeteerorpuppeteer-core. - Whether the failure happens locally, in CI, in a container, or in a cloud runtime, and whether installation and execution use the same user and filesystem.
These distinctions matter: puppeteer normally downloads a compatible Chrome for Testing browser during installation, while puppeteer-core does not download a browser. The bundled browser is Puppeteer’s compatibility-guaranteed route; an externally managed browser is an operator-managed compatibility choice.
Restore a missing browser download
If the package installed but Puppeteer reports that its expected browser is missing, first check whether your package manager blocked dependency install scripts. Without Puppeteer’s install step, the package can be present while Chrome is absent.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
- Check that the project has
puppeteerinstalled, not onlypuppeteer-core, if you expect Puppeteer to supply Chrome. - Review package-manager policy and install logs for skipped or blocked scripts. If your package manager requires explicit approval for dependency scripts, allow Puppeteer’s install script using the mechanism documented for that package manager.
- After installing the package, run the documented recovery command from the project directory:
npx puppeteer browsers install. - Retry the launch. If discovery still fails, compare the browser cache directory used at installation with the one visible to the runtime.
Do not assume every package manager uses identical commands or policy settings. Use the instructions for your installed package-manager version, and check Puppeteer’s installation documentation before copying a command from an old issue or tutorial.
When puppeteer-core is intentional
puppeteer-core is intended for a browser managed elsewhere, including a remote browser setup. It does not install Chrome. Supply a browser through an explicit executable path or a supported channel, as appropriate to your environment. For example, a launch configuration can point at a known executable:
const browser = await puppeteer.launch({ executablePath: '/path/to/chrome' });
Replace the example path with the actual browser binary available in the runtime; it is not a universal path. If you want Puppeteer to manage its compatible browser download, use the puppeteer package instead.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Make installation and runtime agree on the browser cache
Since Puppeteer v19, the default browser cache is ~/.cache/puppeteer. A frequent deployment mismatch occurs when installation downloads Chrome under one user or directory, but runtime runs as another user or looks in a different location. The browser may exist on disk and still be undiscoverable.
You can set PUPPETEER_CACHE_DIR or configure cacheDirectory in Puppeteer’s configuration. Choose a location that is available to both the installation process and the process that launches the browser. If you change the download configuration, rerun browser installation so the browser is placed in the configured cache.
Rank #2
- Check the effective home directory and cache path for both the build step and runtime user.
- In CI or containers, confirm that the cache persists between the install and execution stages if those stages use separate filesystems.
- For cloud build caches that prevent the postinstall step from running, Puppeteer’s troubleshooting guidance discusses placing the cache under
node_modulesfor App Engine and Cloud Functions scenarios. Treat this as a deployment-specific choice, not a universal cache setting.
Verify Node.js, platform, and browser selection
Check the requirements for the exact Puppeteer release in your project rather than relying on a requirement quoted for another version. The system-requirements page surfaced for Puppeteer 25.12.0 specifies Node.js 22.12 or newer and lists Chrome for Testing support on Windows x64, macOS x64/arm64, Debian/Ubuntu Linux x64/arm64, and openSUSE/Fedora Linux x64/arm64. Requirements can change between releases; confirm them against the version actually installed.
If you select a system Chrome or Chromium with an executable path or supported channel, Puppeteer does not guarantee every external-browser combination. Check the binary’s architecture, version, and compatibility with the Puppeteer release. If you do not have a reason to manage Chrome separately, the browser downloaded for Puppeteer is the safer compatibility baseline.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Fix Linux dependency and writable-path failures
A browser can be present and discoverable but fail at startup because the operating system lacks shared libraries Chrome needs. On Linux, inspect the actual browser executable rather than guessing from a generic dependency list:
ldd /path/to/chrome | grep not
Replace /path/to/chrome with the executable Puppeteer is trying to launch. Missing libraries shown by the command need the matching packages for your distribution and release. Consult Puppeteer’s current distribution-specific dependency guidance; package names and availability vary, so a list for a different distribution may not resolve the problem.
WSL and container profiles
For WSL, check both required Linux dependencies and whether the Chrome user can write to the temporary profile directory. Puppeteer allows an explicit userDataDir when you need to put the browser profile in a known writable location:
const browser = await puppeteer.launch({ userDataDir: '/path/to/writable/profile' });
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsUse a directory that exists or can be created and is writable by the process running Puppeteer. Avoid sharing a live profile between concurrent browser processes unless your setup explicitly supports it.
Alpine Linux
Puppeteer’s guide does not describe Alpine as supported out of the box. Compatibility must be established for the specific Puppeteer and Chromium combination and its system dependencies. The troubleshooting page also flags a Chromium timeout issue for Alpine 3.20. Do not treat a timeout on that image as proof that increasing a generic launch timeout is sufficient; first validate the browser, dependencies, and supported configuration.
Investigate sandbox errors without weakening security by default
“No usable sandbox!” requires platform- and binary-specific investigation. Puppeteer documents a case on Ubuntu 23.10 and newer where AppArmor restrictions may block user namespaces for Puppeteer-downloaded Chrome for Testing. Identify the OS release and browser binary, then follow the applicable platform guidance.
Puppeteer strongly discourages running Chrome with --no-sandbox. Disabling the sandbox is not a routine fix for a failed launch: it removes a security boundary and may expose the environment to risk if the browser processes untrusted content. Prefer resolving the supported sandbox configuration or security-policy conflict.
On Windows, sandbox-related failures may involve permissions on the downloaded browser files or an enforced Chrome policy. Check the actual error, file permissions, and applicable organizational browser policy rather than applying a Linux workaround.
Debug CI, containers, and cloud runtimes
If the same application works locally but fails in deployment, compare the environments systematically. A successful local launch does not establish that the deployment image has the same browser, libraries, permissions, or cache.
- Install stage: Did package installation run Puppeteer’s browser-download script, or did policy skip it?
- Filesystem: Is the browser cache persisted and readable by the runtime user?
- Image and libraries: Does the deployed operating system include the browser’s required packages?
- Paths and permissions: Can the runtime write to its temporary directory and browser profile?
- Security: Does the platform enforce sandbox or browser policies that differ from local development?
Puppeteer’s cloud guidance notes that Cloud Run’s default Node.js runtime lacks Chrome system packages. Its App Engine and Cloud Functions notes describe putting the browser cache under node_modules as a way to address discovery when build caching prevents the postinstall step from running. Apply the advice to the specific service and build flow; these are distinct problems—missing OS libraries and missing downloaded-browser visibility—and one setting may not fix both.
Collect useful diagnostics
For browser-install problems, the @puppeteer/browsers documentation describes enabling detailed diagnostics with this environment variable:
NODE_DEBUG="puppeteer:browsers:*"
Use it while reproducing installation or browser-discovery failures to expose cache, file, install, and launcher details. For launch-time output, Puppeteer’s launch options include dumpio, which pipes browser process output to the parent process:
const browser = await puppeteer.launch({ dumpio: true });
Keep the full output, including stderr, alongside the version and platform details. Remove secrets from logs before sharing them; browser arguments, environment variables, or page data may contain sensitive information.
Or skip the browser setup
If your goal is to get a website screenshot rather than control a local Puppeteer browser, ScreenshotNeo offers a screenshot API and MCP server. It does not repair Puppeteer or replace browser automation when you need to interact with a page. A GET request returns an image or PDF; its clean-shot handling can accept consent banners and remove known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status. AI agents can use its MCP tools for screenshots, page information, and PDF capture.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →One-call cURL example (see the ScreenshotNeo API documentation):
Best Value
- Used Book in Good Condition
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Common failure patterns and fixes
| Symptom | Likely layer to inspect | First action |
|---|---|---|
| “Could not find expected browser locally” | Download, cache path, or runtime user | Run npx puppeteer browsers install; align install and runtime cache configuration. |
| “Could not find Chrome (ver. …).” | Browser version discovery or external browser selection | Confirm package/version, install the expected browser, or provide the intended external executable. |
| Browser found, then “Failed to launch chrome!” | OS libraries, architecture, permissions, profile path, or security | Preserve stderr; inspect libraries with ldd on Linux and verify writable paths. |
| “No usable sandbox!” | Platform sandbox policy and browser binary | Identify OS and browser, then investigate the applicable sandbox restriction; do not default to disabling it. |
| Works locally, fails in cloud | Image dependencies, install scripts, cache persistence, or user mismatch | Compare the build and runtime environments, including browser cache and system packages. |
Frequently Asked Questions
Does Puppeteer install Google Chrome Stable?
Its normal install downloads a compatible Chrome for Testing browser. That is distinct from relying on whatever system Chrome happens to be installed.
Can I use a remote browser with Puppeteer?
Yes. puppeteer-core is intended for remote or externally managed browser setups; configure the browser connection or executable according to that setup.
Should I use --no-sandbox in production?
Puppeteer strongly discourages running without a sandbox. Investigate the platform-specific restriction and retain Chrome’s sandbox where possible.
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.
