Fix Puppeteer on CentOS 7 by identifying which layer is failing: Node.js/npm, Puppeteer’s downloaded Chrome, Chrome’s shared libraries, or Linux sandboxing. Install a maintained Node.js version supported by your Puppeteer release, verify that the browser download is present and readable by the service account, install the documented CentOS libraries, and use ldd to identify unresolved dependencies. A working repair is still an interim measure: CentOS Linux 7 reached end of life on June 30, 2024.
First identify which part of the installation failed
“Puppeteer installation” can refer to two separate things: installing the Node.js package and installing the Chrome browser that Puppeteer launches. The npm command can succeed even when Chrome’s download was skipped, put in a different cache, or made inaccessible to the account that runs your application. Other common failures occur after both are installed: Chrome cannot load a shared library, cannot use a Linux sandbox, or is running in an unsuitable environment.
Work through the checks in order. That avoids treating every failure as a missing package and helps preserve Chrome’s security boundary. The package commands below use CentOS 7’s yum; repository and package availability can vary by enabled repositories and architecture.
Check the runtime account and Node.js
Run checks as the same account and in the same service or deployment environment that launches Puppeteer—not only from your interactive login. Confirm the effective user, its home directory, CPU architecture, and access to the project and browser-cache directories:
Recommended Free Tools
#1 Best Overall
whoami
printf 'HOME=%sn' "$HOME"
uname -m
node --version
npm --version
ls -ld "$HOME" .Make sure the project directory is writable where installation requires it, and that the runtime account can read and execute the browser. Puppeteer’s system-requirements guidance says it follows the latest Node.js maintenance LTS line; check the requirements for the Puppeteer version you actually use rather than assuming an old Node installation will work.
Install Puppeteer and verify its Chrome download
For a normal Puppeteer installation, use a compatible maintained Node.js release, then install the package and explicitly run the documented browser-install command:
npm install puppeteer
npx puppeteer browsers installPuppeteer’s installation documentation says npm i puppeteer downloads a compatible Chrome for Testing build, normally under $HOME/.cache/puppeteer. Some package managers or deployment setups block dependency installation scripts. In that case, npm may install Puppeteer while the browser download is absent, leading to an error such as Could not find Chrome (ver. …). Running npx puppeteer browsers install is the documented repair for a missing browser download.
Make the cache consistent across install and runtime
A frequent deployment mismatch is that installation runs as one user but the application runs as another. Each account can have a different HOME and therefore a different default browser cache. The runtime account may not be able to see or execute a browser downloaded into an installer account’s home directory.
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 problemsRank #2
Choose a cache location that both the installer and runtime account can access. For example, set a shared path before installing the browser:
export PUPPETEER_CACHE_DIR=/var/cache/puppeteer
npx puppeteer browsers installConfigure the application to use the same cache setting, or configure Puppeteer’s cacheDirectory and reinstall the browser after changing it. Check permissions on every directory in the path, not just the Chrome executable: the service account needs to traverse parent directories and read and execute the browser files. Do not assume that setting the variable in an administrator’s shell also sets it for a system service; configure the service environment deliberately.
Install the CentOS 7 libraries and fonts Puppeteer lists
If Chrome is present but exits at startup or reports a shared-library problem, install Puppeteer’s documented CentOS dependencies. The official list is:
alsa-lib.x86_64
atk.x86_64
cups-libs.x86_64
gtk3.x86_64
ipa-gothic-fonts
libXcomposite.x86_64
libXcursor.x86_64
libXdamage.x86_64
libXext.x86_64
libXi.x86_64
libXrandr.x86_64
libXScrnSaver.x86_64
libXtst.x86_64
pango.x86_64
xorg-x11-fonts-100dpi
xorg-x11-fonts-75dpi
xorg-x11-fonts-cyrillic
xorg-x11-fonts-misc
xorg-x11-fonts-Type1
xorg-x11-utilsAfter installing the dependencies, Puppeteer’s CentOS troubleshooting guidance also says to update NSS:
yum update nss -yIf a package is unavailable, retain the exact yum error and check the enabled repositories and machine architecture. Do not silently substitute a package with a similar-sounding name: the error may indicate a repository or lifecycle problem rather than the absence of a direct replacement.
Use ldd to find the exact missing shared library
Inspect the actual Chrome executable Puppeteer downloaded. Replace the example path with the path to that executable in your configured browser cache:
ldd /path/to/chrome | grep notAny output containing not found identifies an unresolved shared library for that executable. Use that evidence to guide package investigation, then rerun the check after installing dependencies. An empty result means this particular check found no unresolved entries; it does not establish that the browser has correct permissions, can use a sandbox, has suitable fonts, or can run in the application’s display configuration.
Fix “No usable sandbox!” without weakening security unnecessarily
Puppeteer’s troubleshooting documentation explains that Chrome can crash with No usable sandbox! when there is no suitable sandbox available. Treat this as a security and host-configuration problem, not as an ordinary missing-library error. Prefer a correctly configured Linux sandbox and run Chrome as a non-root account.
Only if the environment cannot provide a sandbox and the pages are fully trusted should you consider this narrowly scoped fallback:
const browser = await puppeteer.launch({
args: ['--no-sandbox'],
});Puppeteer strongly discourages running without a sandbox. The flag changes Chrome’s security boundary; it is not a general installation fix and should not be applied indiscriminately to a service that may visit untrusted or user-supplied URLs.
Use the error message to choose the next check
| Symptom | Likely cause | Next action |
|---|---|---|
Could not find Chrome (ver. …) |
The browser postinstall was blocked, the configured cache changed, or installation and runtime use different accounts. | Run npx puppeteer browsers install; compare the install and service HOME and cache settings, then check browser permissions. |
Chrome exits immediately; ldd prints not found |
A shared library required by Chrome is missing. | Install the documented CentOS dependencies, investigate any yum errors, and repeat the ldd check. |
No usable sandbox! |
The host cannot provide a usable sandbox or its permissions are unsuitable. | Configure a real sandbox and use a non-root browser account. Consider --no-sandbox only for fully trusted content when no sandbox is available. |
| Fonts render as squares or text is absent | Relevant X11 or font packages may be missing. | Install the listed X11 and font packages, then retest the affected pages. |
| Module-resolution errors on an old Node.js version | The Node.js runtime may not meet the Puppeteer version’s requirements. | Move to a maintained Node.js release compatible with the Puppeteer version in use. |
Make a successful launch reproducible
Once the browser launches, make the working environment explicit so a later deployment does not recreate the same failure. Record the Node.js and Puppeteer versions used, the identity of the service account, and the browser-cache location and permissions. Ensure the production service receives the same cache configuration used during browser installation, and retain the package-install output if scripts or downloads are restricted in your build environment.
Test the exact operation your application needs under the service account: launch Chrome, load a page, and produce the expected output. A successful npm install or an empty ldd result alone does not test all of those conditions. If the service visits untrusted pages, keep sandboxing in the design rather than treating a no-sandbox launch as a routine workaround.
Best Value
CentOS 7 repairs should be treated as temporary
The CentOS Project records June 30, 2024 as the end-of-life date for CentOS Linux 7. Red Hat likewise says CentOS 7 updates ended on that date and describes migration to RHEL, with optional extended support, as continuity options. A local repair may restore a legacy workload, but it does not change the host’s lifecycle status. Plan a move to a supported operating system; where enterprise continuity is required, assess the migration and support options with Red Hat.
The durable choice depends on the operational constraints: preserving Chrome’s sandbox, making browser downloads and cache locations reproducible, leaving an end-of-life operating system, and deciding who owns ongoing operating-system maintenance. Repairing CentOS 7 locally can be a bridge, not a substitute for resolving the platform lifecycle risk.
Or skip the browser setup
If your goal is to capture website screenshots rather than operate Chrome on your CentOS host, ScreenshotNeo is a screenshot API and MCP server. A single request returns an image or PDF; the API can handle browser setup outside your application environment. This is an alternative to maintaining local Puppeteer, not a fix for a Puppeteer installation you still need to run.
For example, save a WebP screenshot of Stripe with cURL:
Free tools Windows power users keep installed
One-click scans. No signup required.
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 the request options. Cookie banners and consent prompts, newsletter popups, and chat widgets can be removed before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include page-verdict and billing headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients such as Claude and Cursor. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Frequently Asked Questions
Does fixing Puppeteer on CentOS 7 make that server a supported long-term platform?
No. A successful browser launch repairs an application dependency, not the operating system’s end-of-life status. Treat the repair as interim and plan an operating-system migration.
Should I use `–no-sandbox` if Chrome still fails after installing the libraries?
Not by default. First diagnose the actual error and configure Chrome’s Linux sandbox; the flag is only a last-resort option for fully trusted content when a sandbox cannot be provided.
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 & 11Quick 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.
