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 →In brief: Puppeteer’s spawn /usr/bin/chromium-browser ENOENT means the Node process cannot find an executable at that exact path in the environment where it is running. Check the path inside the failing machine, container, or CI job; confirm the file is executable; then either install Puppeteer’s managed browser or point executablePath to a browser that is actually present. Missing libraries and sandbox failures produce different errors and need different fixes.
What ENOENT means in Puppeteer
ENOENT is the operating system’s “no such file or directory” result. At browser launch, it normally means that the executable path supplied to Node does not exist in that runtime. A path that works on your laptop, in an earlier Docker stage, or on a host machine does not prove that the same path exists in a CI job or production container.
The frequently copied /usr/bin/chromium-browser example is a possible Linux path, not a universal one. Distribution, package, image, CPU architecture, and browser version all affect the filename and location.
Diagnose the launch target first
Inspect Puppeteer configuration
Search your puppeteer.launch() call and environment for executablePath and PUPPETEER_EXECUTABLE_PATH. Log the resolved value in the failing environment. If no custom path is required, remove the override and use Puppeteer’s managed browser after ensuring it was installed.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#1 Best Overall
const puppeteer = require('puppeteer');
const browser = await puppeteer.launch({
// Set this only when the target runtime has this exact file.
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
});An alternate binary is supported through executablePath, but Puppeteer documents that compatibility is guaranteed only for its bundled browser. A system Chromium build can differ in protocol support, flags, or revision, so treat this as an intentional deployment choice rather than a generic repair.
Check from the same runtime and user
Run these commands inside the failing CI job, final container image, or cloud instance, using the account that starts Node:
printf 'path=%sn' "$PUPPETEER_EXECUTABLE_PATH"
command -v chromium || true
command -v chromium-browser || true
ls -l /usr/bin/chromium /usr/bin/chromium-browser 2>/dev/null || true
test -x "$PUPPETEER_EXECUTABLE_PATH" && echo executable || echo missing-or-not-executableIf the configured variable is empty, points to a host-only location, or names a non-executable file, correct the deployment configuration or install the browser in that image. Do not “fix” the error by guessing another path; discover the path provided by the package in the target environment.
Install Puppeteer’s browser when the download was skipped
Puppeteer normally downloads a compatible browser during package installation. Package-manager policies can block install scripts, leaving the Node package present but the browser absent. This can occur with npm policies, pnpm, Yarn Berry, Bun, or Deno configurations that require explicit approval for scripts.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #2
- Review the package-manager output and configuration for ignored or blocked install scripts.
- Run the install step in the build that produces the runtime image, not only on a developer workstation.
- Install the browser explicitly when needed:
npx puppeteer browsers installAfterward, launch without a hard-coded system path, or configure Puppeteer to use the cache location used by your build. If the default cache is unavailable, set PUPPETEER_CACHE_DIR or the equivalent Puppeteer configuration cache directory, and ensure that directory is copied into the final image and readable by the runtime user.
Make CI and Docker images self-contained
Continuous integration
Put browser installation and verification in the same job that runs tests. A multi-stage pipeline can otherwise install Chromium in one image and execute Node in another. Add a diagnostic step that prints the Puppeteer version, Node version, operating system, architecture, resolved executable path, and an existence check. Keep the check before tests so a packaging regression fails with a useful message.
Docker
Install the browser and its system libraries in the final runtime image. Copying only node_modules from a build stage is insufficient if the browser cache was left behind. Verify the file after the final USER change; root-only permissions can turn a present browser into a launch failure.
The exact Dockerfile depends on the base distribution and architecture. Avoid copying a dependency list written for a different image. Chromium packages and library names change, and Puppeteer’s documentation warns that old lists can become outdated.
Cloud Run and managed runtimes
Puppeteer’s Cloud Run guidance notes that the default Node.js runtime does not include the system packages required by Headless Chrome. Use a custom Dockerfile that installs the browser and dependencies, then verify the executable from inside that image. Choosing a hosting service alone does not supply a missing browser.
Alpine Linux
Chrome does not work on Alpine out of the box. Alpine’s musl-based environment requires a compatible browser build and dependency set. Confirm that the Puppeteer version, browser revision, base image, and architecture are supported together instead of applying an old Alpine recipe unchanged.
Separate ENOENT from the next launch error
Missing shared libraries
If the executable exists and Node can spawn it, the next error may report a missing shared object or an immediate browser exit. That is no longer an ENOENT path problem. On Linux, inspect dependencies with:
ldd /path/to/chrome | grep notInstall the missing packages for the specific distribution and browser package. Puppeteer lists common Debian and Ubuntu dependencies and points to Chromium’s current package requirements; use those lists as a starting point and verify names for your release.
Free tools Windows power users keep installed
One-click scans. No signup required.
Sandbox errors
Messages such as “No usable sandbox” indicate permissions or sandbox configuration, not an absent executable. Puppeteer strongly discourages disabling the sandbox. Configure a working sandbox for the container or host. Only consider --no-sandbox as a narrowly constrained workaround when the actual error is a sandbox failure, and understand that it reduces isolation; it is not a blanket ENOENT fix.
A reliable repair sequence
- Capture the exact error and command. Record the complete path Node attempted to spawn and the environment in which it occurred.
- Resolve configuration. Find every
executablePathandPUPPETEER_EXECUTABLE_PATHsetting, including CI secrets and Docker environment entries. - Verify the file in place. Use
ls -l,test -x, andcommand -vinside the failing runtime and as the Node user. - Choose one browser source. Remove an unnecessary override and install Puppeteer’s browser, or install a system browser and set its real path deliberately.
- Preserve the installation. Copy the Puppeteer cache and libraries into the final image; do not rely on a temporary build layer.
- Retest, then classify the new error. Library failures, sandbox failures, navigation timeouts, and bot checks require separate remedies.
- Check versions and architecture. Compare Node, Puppeteer, browser, operating system, and CPU architecture with the requirements for the version you actually deploy. A “Next” requirements page may describe unreleased or upcoming packages.
Common symptoms and fixes
| Symptom | Likely cause | Action |
|---|---|---|
spawn ... ENOENT |
Path absent in the runtime | Verify inside the container or CI job; install a browser or correct the path. |
| Browser package installed, no executable | Install script or download blocked | Review package-manager policy and run npx puppeteer browsers install. |
error while loading shared libraries |
System dependency missing | Run ldd /path/to/chrome | grep not and install distro-specific libraries. |
No usable sandbox |
Sandbox permissions or container setup | Configure a sandbox; do not treat --no-sandbox as an ENOENT solution. |
| Works locally, fails in deployment | Different image, user, architecture, or cache | Reproduce checks in the final runtime image and retain browser files between build stages. |
Performance, reliability, and maintenance
A bundled browser gives Puppeteer its strongest compatibility guarantee, but it increases installation size and requires a persistent cache in deployment. A system browser can reuse an image-level package and may simplify patching, yet you own path discovery and compatibility testing. Pin your Node and Puppeteer versions, rebuild images when browser security updates are required, and run a smoke test that launches and closes a page before the full test suite.
For parallel CI jobs, avoid having every job download the same browser independently. Use a cache keyed by the Puppeteer version and architecture, while still validating that the cache is present in the job that launches Node. Treat browser downloads, Linux libraries, and sandbox configuration as separate build inputs.
Or skip the browser setup
If your goal is a clean website image rather than maintaining Chromium, ScreenshotNeo provides a website screenshot API and MCP server. Its one-call request accepts a URL and 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 cleanup step can be disabled.
Only clean shots are billed. 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. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
Best Value
- Used Book in Good Condition
Use the API documentation at https://screenshotneo.com/docs/ for the complete option set. A minimal request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo includes full-page capture with lazy-image loading, CSS-selector element capture, dark mode, 12 device presets and arbitrary viewports, retina scale, PDF paper and page controls, HTML/CSS rendering, custom JavaScript and CSS, pre-capture clicks, selector hiding, selector or network-idle waits, ad and tracker blocking, custom headers, cookies, user agents and authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Common parameter names used by other screenshot APIs also work.
The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing provides two months free. Create a free ScreenshotNeo account to start.
Recommended Free Tools
Frequently Asked Questions
Should I always set executablePath to /usr/bin/chromium-browser?
No. That path is environment-specific. Discover the executable in the runtime that launches Node, or let Puppeteer use its managed browser.
Does reinstalling Node fix ENOENT?
Usually not. ENOENT concerns the browser executable path or its presence in the runtime; reinstalling Node does not install a missing browser.
Can a browser exist but still fail to launch?
Yes. Once the path is found, missing shared libraries, sandbox permissions, architecture mismatches, or incompatible browser revisions can cause a different launch failure.
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.
