If Puppeteer reports that Chrome or Chrome Headless Shell is missing in CI, first identify whether the failure occurs during dependency installation, browser download, cache restore, archive extraction, or puppeteer.launch(). Then fix that stage: allow or run Puppeteer’s installer, keep the browser cache consistent between jobs, check the configured download host and version, or resolve a runtime dependency. Headless Shell is a separate browser binary, so changing launch flags alone will not repair a failed download.
First identify which browser and stage are failing
Collect the full error and these details before changing the workflow:
- The installed
puppeteerorpuppeteer-coreversion. - Node.js version, package manager and version, runner operating system, and CPU architecture.
- Whether the error appears during dependency installation, an explicit browser-install command, or
puppeteer.launch(). - Whether installation and execution happen in the same job, container, user account, and home directory.
- The configured Puppeteer cache directory, download base URL, and browser version, if any.
Puppeteer’s installation guide says the package downloads Chrome for Testing and Chrome Headless Shell; the separate shell download has been included since Puppeteer v21.6.0. The headless guide distinguishes regular headless Chrome, selected with headless: true, from the old headless mode using the separate shell binary, selected with headless: 'shell'. The shell does not behave exactly like regular Chrome. See the Puppeteer headless modes guide and installation guide.
Make sure the workflow actually needs Headless Shell. If it does, keep the shell browser mode and repair its installation. If regular headless Chrome meets the requirement, switching modes may avoid a dependency on the shell artifact, but it changes browser behavior; it is not a general fix for a broken download.
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
- [INTEL POWERED CONTENT] - Built with a 8th Generation Hexa-Core Intel i5 and 32GB of DDR4 RAM; Modern, Windows 11 ready, with 4K support, Executive multitasking, media streaming and smooth, multi-tab web browsing; Perfect as an all-purpose multimedia computer; built for content creators; Plenty of RAM and Mass storage for photo and video editing powered by Intel HD 630
- [LATEST WIRELESS TECH] - This Dell Desktop Computer easily connects to the internet through the Built In WiFi / Bluetooth
- [SOLID STATE STORAGE] - This Dell Computer setup comes with an ultra-fast 1TB Solid State Drive (SSD); Setup as the primary boot device; Boot and load programs with lightning speed ; Additional expansion available
- [BUY & OWN WITH CONFIDENCE] - From the world's largest Microsoft Authorized Refurbisher; Quality Guarantee and Free Tech Support; Award-winning Customer Service; | Support Sustainable Business
- [MODERN HI-SPEED PORTS] - USB 3.0 (x4) | USB 2.0 (x4) | DisplayPort (x1) | HDMI Port (x1) | Audio Combo Jack (x1) | Audio Out (x1) | RJ-45 Ethernet (x1) | Internal SATA (x3)
If the browser is missing immediately after package installation
Check whether lifecycle scripts were blocked
Puppeteer’s automatic browser download is normally tied to package installation. Package-manager security settings or project policy can block lifecycle scripts, leaving the package installed but no browser downloaded. The installation guide warns that this can lead to a Could not find Chrome (ver. ...) error. Review the package-manager output and project configuration for disabled scripts before retrying the job.
There are two supported approaches: explicitly run Puppeteer’s browser installer in the workflow, or configure the package manager to allow Puppeteer’s install script. The exact allow-list syntax varies by package manager and version, so use the form documented for the version pinned by the project rather than copying a command intended for another release. Puppeteer’s installation guide documents the installer and package-manager-specific script-policy options.
Install the browser explicitly
For a project using the puppeteer package, an explicit install step makes the download stage visible in CI logs. Run it after dependencies are installed and before the job starts the application or test suite:
npx puppeteer browsers installUse the project’s locally installed Puppeteer CLI where possible; that ties the installer to the package version in the lockfile. If this command fails, diagnose its network, version, and extraction output as a browser-install problem rather than proceeding to launch-flag changes.
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 →Rank #2
- Model: Dell OptiPlex 7050 Small Form Factor (SFF)
- Processor: Intel Core i7-7700 3.60 GHz
- Memory: 32GB DDR4 Ram
- Storage: 1TB Solid State Drive (SSD) Fast Boot + Storage
- Operating System: Windows 11 Pro (64-bit)
Check whether the project uses puppeteer-core
puppeteer downloads a compatible browser as part of its installation workflow. puppeteer-core does not download Chrome; it is intended for setups where the browser is managed separately. With puppeteer-core, the CI job must install or provide a browser and configure Puppeteer to use it. Do not expect enabling the puppeteer lifecycle script to install a browser when the project depends only on puppeteer-core.
If installation succeeds but a later CI step cannot find the browser
Use the same cache path at install and runtime
Since Puppeteer v19, the default browser cache is ~/.cache/puppeteer. A download can appear to succeed in one step and still be unavailable later if the next step runs in another container, under another user, with a different home directory, or on a fresh ephemeral runner. Puppeteer supports setting the cache location explicitly with PUPPETEER_CACHE_DIR or the cacheDirectory configuration option. See the Puppeteer configuration guide.
For example, choose a project cache path and set it for both installation and execution:
export PUPPETEER_CACHE_DIR="$PWD/.cache/puppeteer"
npx puppeteer browsers install
node your-script.jsThis shell example assumes both commands run from the same directory in the same job. If your CI splits installation and execution into separate jobs, persist and restore the cache between them, and ensure both jobs use the same configured path. If you change Puppeteer cache configuration, Puppeteer’s troubleshooting guide says to reinstall so the change takes effect.
Rank #3
- IMMERSIVE 24 INCH DISPLAY: Experience stunning clarity on a Full HD IPS screen with ultra-thin bezels, offering a 90% screen-to-body ratio that makes everything from spreadsheets to streaming come alive with vibrant colors and crisp details.
- POWERFUL INTEL PROCESSING: Tackle demanding tasks with ease thanks to the Intel processor and 16GB of high-speed memory, delivering smooth performance whether you're multitasking between applications or running productivity software.
- GENEROUS STORAGE: Store all your important files, photos, and programs with blazing-fast solid state drive technology that ensures quick boot times, rapid file access, and plenty of space for your digital life.
- ENHANCED PRIVACY AND COLLABORATION: Work confidently with the pop-up privacy camera that tucks away when not in use, plus dual microphones with noise reduction for crystal-clear video calls that keep you connected professionally.
- ECO-CONSCIOUS DESIGN: Feel good about your purchase with an EPEAT Gold registered and ENERGY STAR certified computer that combines premium performance with responsible environmental manufacturing practices.
Key restored caches to the browser environment
A CI cache that includes downloaded browser artifacts should distinguish the Puppeteer/browser version and runner platform. Browser downloads are version- and platform-specific; reusing an artifact across incompatible versions or architectures can restore the wrong files. The Puppeteer documentation does not prescribe a cache-key format for a particular CI provider, so adapt the key to your provider and include the project’s pinned Puppeteer version and relevant OS/architecture inputs.
If the download host is unreachable or the wrong browser version is fetched
Check whether CI can reach Puppeteer’s configured download host. The Headless Shell configuration exposes a download base URL and version setting, with environment-variable overrides; the documented default host is Chrome for Testing’s public storage endpoint. A mirror can help when network policy blocks that host, but it must serve the expected artifact and preserve the required path layout. The base URL may need a path prefix and should not end in a slash.
Those option names and details are version-sensitive: some are documented in Puppeteer’s next-version configuration reference. Check the API reference matching the Puppeteer release in your lockfile before setting an override. Avoid changing both the browser version and the download host at once; change one variable, rerun the explicit installer, and inspect its logs.
Prefer Puppeteer’s bundled, pinned browser unless there is a specific operational reason to manage versions independently. Puppeteer maps releases to supported Chrome versions in its supported browsers guide, and its launch API cautions that an arbitrary executable path is not guaranteed to work. If you intentionally supply another browser, validate that exact Puppeteer/browser pairing rather than assuming any installed Chrome is interchangeable.
Rank #4
- This Certified Refurbished product is tested and certified to look and work like new. The refurbishing process includes functionality testing, basic cleaning, inspection, and repackaging. The product ships with all relevant accessories, a minimum 90-day warranty, and may arrive in a generic box. Only select sellers who maintain a high-performance bar may offer Certified Refurbished products on Amazon.com.
- Dell Optiplex 3050 SFF Desktop computer PC, Intel Quad Core i5-6500 up to 3.6GHz, 16GB DDR4, 256GB SSD
- Includes: USB Keyboard & Mouse, USB WiFi adapter, Microsoft office 30 days free trail.
- Port: Front: USB 3.0(2), USB 2.0(2); Rear: DP, HDMI, USB 3.0(2), USB 2.0(2), RJ-45.
- Support 4K (3840x2160) Dual display, makes it easy to connect two monitors at the same time, and you can expand working Windows, mirror content, or expand a single window across multiple monitors.
If the download completes but extraction or launch fails
Check Node.js, operating system, and architecture
Compare the runner against the requirements for the Puppeteer version actually installed. The current Puppeteer system requirements page, version 25.12.0 at the time of the cited documentation, lists Node.js 22.12 or later and Chrome for Testing support on Windows x64; macOS x64 and arm64; Debian/Ubuntu Linux x64 and arm64; and openSUSE/Fedora Linux x64 and arm64. These requirements can change, so verify the page for the pinned release: Puppeteer system requirements.
Check archive extraction tools and Linux libraries
The same requirements page identifies tar and PowerShell or unzip as extraction prerequisites, unless the optional yauzl dependency is installed. If the installer downloaded an archive but could not unpack it, check the relevant tool and its availability in the runner image. If extraction succeeds but launch reports missing shared libraries, install the required Linux distribution packages for the supported environment; that is a runtime dependency issue, not evidence that the download itself failed.
Do not treat sandbox flags as a download fix
A sandbox or permissions error after the browser is present belongs to launch configuration. Puppeteer’s troubleshooting page includes Linux sandbox guidance, but its sandbox section is marked as mostly out of date. Do not add --no-sandbox as a universal CI remedy: first identify the specific launch error and apply an environment-appropriate fix.
A minimal CI verification sequence
- Confirm the dependency. Check the lockfile and installed package to determine whether the project uses
puppeteerorpuppeteer-core. - Confirm the intended mode. Verify whether the code requests
headless: 'shell'or regular headless Chrome. - Install visibly. Run
npx puppeteer browsers installafter dependencies are installed, with lifecycle scripts allowed if relying on automatic installation. - Keep paths stable. Set
PUPPETEER_CACHE_DIRconsistently if install and runtime do not share the default home directory. - Check compatibility. Match Puppeteer version, browser artifact, Node version, operating system, architecture, and extraction tools.
- Separate stages in the logs. Determine whether the error is download, extraction, cache lookup, missing system library, or browser launch before changing configuration.
Or skip the browser setup
If your task is to capture website screenshots rather than run a full Puppeteer browser workflow, ScreenshotNeo is a website screenshot API and MCP server: one GET request with a URL returns a PNG, JPEG, WebP, or PDF. For example, see the API documentation for parameters and response details:
PC 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 & 11Crashes, 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 minuteBest Value
- Connectivity: Includes WiFi, Bluetooth, and LAN for wireless and wired connections
- Memory: Features 16GB DDR4 RAM for smooth multitasking and performance
- Storage: Combines 500GB SSD and 1TB HDD for ample storage space
- Graphics: Integrated Intel UHD Graphics 630 for crisp visuals and video playback
- Design: Sleek desktop tower with black color and slim profile for modern look
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpScreenshotNeo accepts cookie/consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. This is a screenshot service, not a replacement for Puppeteer when your tests need browser interaction or application-specific execution.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Puppeteer install Chrome Headless Shell automatically?
The puppeteer package’s installation workflow downloads the browser artifacts, including Headless Shell since v21.6.0, unless installation scripts are blocked. puppeteer-core does not download a browser.
Can I switch to regular headless Chrome to fix a Headless Shell download failure?
Only if your use case can use regular headless Chrome instead. It uses a different browser mode and artifact, and may behave differently; it does not repair the shell download.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsIs ScreenshotNeo a drop-in replacement for Puppeteer?
No. ScreenshotNeo provides website screenshot and PDF capture through an API and MCP tools; it does not replace Puppeteer for tests requiring custom browser interaction or application-specific execution.
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.
