Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →spawn /usr/bin/chromium-browser ENOENT means the Node process cannot find an executable at the path it was told to launch. Fix it in the environment that actually runs Puppeteer: verify the configured path, install Puppeteer’s browser (or a system browser) there, confirm permissions, and only then investigate separate library or sandbox errors. The path shown in the message is a CI example, not a universal Chromium location.
What ENOENT means in Puppeteer
At launch time, Puppeteer asks Node.js to start Chromium. ENOENT is the operating system’s “no such file or directory” result. In practice, either the file named by executablePath does not exist in that runtime, the environment variable supplying the path is wrong, or Puppeteer’s managed browser was never downloaded.
A path that works on a developer laptop says nothing about a GitLab job, Docker image, serverless runtime, or another machine. Every check must run inside the same container, CI job, or deployed instance that executes Node.
1. Identify the browser Puppeteer is trying to launch
Inspect launch options and environment variables
Search your code and deployment configuration for executablePath and PUPPETEER_EXECUTABLE_PATH. Log the value without exposing secrets, then check it in the failing runtime.
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
- 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.
const puppeteer = require('puppeteer');
console.log('Configured executable:', process.env.PUPPETEER_EXECUTABLE_PATH || '(Puppeteer default)');
const browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || undefined,
});If you do not need a system-installed browser, remove the custom path and let Puppeteer use its bundled browser. Puppeteer’s API defines executablePath as an alternate binary location and warns that compatibility with alternate browsers is not guaranteed: “Puppeteer is only guaranteed to work with the bundled browser, so use this setting at your own risk.”
Check the path as the Node user
Run these commands in the final image or CI step, using the same user that starts your application:
printf 'PATH=%sn' "$PATH"
echo "PUPPETEER_EXECUTABLE_PATH=$PUPPETEER_EXECUTABLE_PATH"
ls -l "$PUPPETEER_EXECUTABLE_PATH"
test -f "$PUPPETEER_EXECUTABLE_PATH" && echo "file exists"
test -x "$PUPPETEER_EXECUTABLE_PATH" && echo "file is executable"Replace the variable with the literal path if it is not set. A missing file, a directory at that location, or a file without execute permission explains an ENOENT or a closely related permission error. Do not assume /usr/bin/chromium-browser; package names and locations differ by distribution, image, operating system, and architecture.
2. Install Puppeteer’s managed browser when appropriate
The simplest deployment is usually Puppeteer’s downloaded browser. Package-manager policies can block install scripts, leaving the JavaScript package installed while its browser is absent. This is common when npm, pnpm, Yarn Berry, Bun, or Deno is configured to require explicit approval for lifecycle scripts.
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 minuteWindows 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 reinstallRank #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.
Install after dependency installation
From the project directory, run:
npx puppeteer browsers installRun it during the image build or CI install stage, not only on your workstation. Confirm that the resulting cache is available in the runtime stage. If you use a multi-stage Docker build, copy the Puppeteer browser cache into the final image or perform the installation again there.
Make the cache location deliberate
Set PUPPETEER_CACHE_DIR (or the equivalent Puppeteer configuration setting) when the default home directory is read-only, ephemeral, or different between build and runtime. The directory must be readable and executable by the application user. A successful build followed by an empty runtime cache produces the same symptom as a failed download.
3. Verify the installation inside CI, Docker, or cloud
Containers and multi-stage builds
Install the browser and its operating-system dependencies in the image that starts Node. A browser installed in a builder image is not automatically present in the final image. Add a diagnostic layer to your build or startup script:
node --version
npm --version
npx puppeteer --version
find / -type f ( -name chrome -o -name chromium -o -name chromium-browser ) 2>/dev/null | head -20Use the discovered path only if it is the browser you intend to run, and set executablePath accordingly. Keep the Puppeteer, browser, Node.js, Linux distribution, and CPU architecture versions compatible.
Recommended Free Tools
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.
CI jobs
Make browser installation an explicit CI step and run the existence test after it. A host installation does not carry into an isolated runner. Cache directories can also be restored with the wrong ownership or omitted from the job entirely.
Cloud Run and similar managed runtimes
Puppeteer’s Cloud Run guidance notes that the default Node.js runtime lacks 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. This is deployment setup, not a universal ENOENT workaround.
Alpine Linux
Chrome does not support Alpine out of the box. Choose a browser and dependency combination documented for your exact Puppeteer version, or use a compatible Debian/Ubuntu-based image. Do not copy an old Alpine recipe without checking current version requirements.
4. Distinguish ENOENT from the next launch failure
Once the executable exists and Node can spawn it, the error often changes. Diagnose the new message rather than continuing to change paths.
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
Missing shared libraries
A browser can be present yet exit immediately because a dynamic library is missing. On Linux, Puppeteer documents this check:
ldd /path/to/chrome | grep notInstall the missing libraries for your exact distribution, architecture, and browser build. Puppeteer lists common Debian and Ubuntu dependencies, but package lists can become outdated; use the current requirements for the image you are building. A missing library is not the cause of the original ENOENT unless the runtime output identifies it.
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 constrained workaround when the actual error is a sandbox failure, and understand that it reduces isolation:
const browser = await puppeteer.launch({
args: ['--no-sandbox', '--disable-setuid-sandbox'],
});Do not add these flags to “fix” ENOENT.
5. Choose bundled Chromium or a system browser
| Choice | What you must provide | Trade-off |
|---|---|---|
| Puppeteer-managed browser | Allow the browser install script or run npx puppeteer browsers install; preserve its cache. |
Best-supported pairing, but the download must occur in every build/runtime where it is needed. |
| System browser | Install Chromium/Chrome and dependencies; set the real path in executablePath. |
Can reuse an image-wide browser, but Puppeteer does not guarantee compatibility with it. |
Use the bundled browser unless your deployment standard requires a system package. If you select a system browser, record its version and path as part of the image build rather than hard-coding a path copied from another machine.
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.
6. A repeatable repair procedure
- Capture the complete error. Keep the first failing command and the runtime name, image, operating system, architecture, Node version, and Puppeteer version.
- Print the launch target. Resolve
executablePathandPUPPETEER_EXECUTABLE_PATHinside the failing process. - Test existence and execute permission. Use
ls -l,test -f, andtest -xas the application user. - Decide on the browser source. Remove an unnecessary custom path, or install the intended system browser in the runtime image.
- Install the managed browser if needed. Run
npx puppeteer browsers installand configure a persistent, readable cache. - Rebuild the final artifact. Ensure a multi-stage build, CI cache, or deployment process does not discard the browser.
- Retry and classify the new error. If it is a library failure, run
ldd; if it is a sandbox failure, fix sandbox permissions. Do not mix these branches. - Check version and platform alignment. Compare Node, Puppeteer, browser, distribution, and architecture with the requirements for the exact released Puppeteer version. A “Next” requirements page can describe unreleased changes.
Common symptoms and fixes
| Symptom | Likely cause | Action |
|---|---|---|
spawn ... ENOENT |
Configured file is absent in the runtime. | Inspect the resolved path; install the browser there or remove the stale override. |
| Path exists locally but not in CI | CI is isolated or uses another image. | Install and verify inside the CI job. |
| Browser cache exists during build, absent at runtime | Cache was not copied, mounted, or permitted. | Set PUPPETEER_CACHE_DIR and preserve ownership and contents. |
error while loading shared libraries |
OS dependency is missing. | Run ldd /path/to/chrome | grep not; install distro-specific packages. |
| “No usable sandbox” | Sandbox permissions or kernel configuration. | Configure a sandbox; avoid disabling it unless this is the actual constrained failure. |
| Works on Debian image, fails on Alpine | Unsupported or mismatched browser/dependency combination. | Use documented Alpine-compatible versions or a supported base image. |
Or skip the browser setup
If your goal is a clean website image rather than controlling Chromium yourself, ScreenshotNeo provides a website screenshot API. It accepts consent banners before capture 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 report the page verdict and billing status.
One GET request returns PNG, JPEG, WebP, or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for all options. The same endpoint supports full-page captures with lazy images, CSS-selector element shots, dark mode, 12 device presets or custom viewports, retina scale, PDF paper settings and page ranges, custom CSS and JavaScript, clicks, selector/delay/network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage data, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, easing migrations.
Python
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf 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, and every feature is available on every plan. Sign up free.
Performance, reliability, and cost considerations
- Build time: downloading a managed browser increases image-build or CI time, so cache it deliberately without allowing a stale cache to hide a failed installation.
- Startup time: launching a browser for every request is expensive; reuse a browser process where your workload and isolation model permit it.
- Reliability: pin compatible Node, Puppeteer, browser, base-image, and architecture versions, then run a smoke test in the final artifact.
- Security: keep Chromium sandboxed, run as a non-root user where practical, and treat cookies, authorization headers, and captured pages as sensitive data.
- Cost: a system browser may reduce repeated downloads, while a managed screenshot API transfers browser maintenance and failed-capture handling to the service. Compare the operational work you actually need rather than assuming either option is universally cheaper.
Frequently Asked Questions
Should I install a package named chromium-browser?
Not necessarily. Package names and executable locations vary by operating system and distribution. Discover the browser provided by the target image and configure that actual path, or use Puppeteer’s bundled browser.
Can changing Puppeteer’s executablePath solve every launch error?
No. It can correct an absent or incorrect path. Once the executable is found, missing libraries, sandbox permissions, browser compatibility, or architecture problems require their own fixes.
Why does Puppeteer work after npm install locally but fail in deployment?
The deployment may block install scripts, use a different user or home directory, discard the browser cache in a multi-stage build, or run an image without the required browser and libraries.
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.
