When Puppeteer fails on CentOS 7, first identify which layer is broken: the Node.js runtime, Puppeteer’s Chrome download or cache, missing operating-system libraries, or Chrome’s sandbox. Fix that layer rather than reinstalling packages at random. The commands below provide a checkable sequence; because CentOS Linux 7 reached end of life on June 30, 2024, treat a repair as interim and plan to migrate the host.
Separate the four common failure layers
Puppeteer installation involves more than adding a Node package. Its browser download can be skipped or saved in a cache that the service account cannot access; Chrome can lack shared libraries; or Chrome can be unable to start with a usable sandbox. Those problems produce different symptoms and need different fixes.
- Node.js or module errors: check whether the installed Node.js release is supported by the Puppeteer version in use.
- “Could not find Chrome”: check whether the browser download ran and whether the runtime account can see its cache.
- Missing libraries or an immediate exit: inspect the Chrome executable with
ldd. - “No usable sandbox!”: address the host’s sandbox and privilege configuration; do not treat disabling the sandbox as a routine install step.
Run the checks as the same account, in the same environment, that launches Puppeteer in production. A successful install under an administrator’s home directory does not establish that a service account can read or execute that browser.
Check Node.js, the runtime user, and directory access
Use a maintained Node.js release supported by your installed Puppeteer version. Puppeteer’s system-requirements guidance follows the latest Node.js maintenance LTS line, but compatibility still depends on the Puppeteer version you installed. If errors mention unsupported syntax, module resolution, or runtime features, verify both versions before changing Chrome packages.
#1 Best Overall
From the service’s actual shell or deployment environment, check the effective user, home directory, CPU architecture, and relevant directory permissions:
id
printf 'HOME=%sn' "$HOME"
node --version
npm --version
uname -m
pwd
ls -ld . "$HOME" "$HOME/.cache" "$HOME/.cache/puppeteer" 2>/dev/nullThe final ls command may report that a directory does not exist; that is useful when checking whether the browser has ever been cached in that home directory. Confirm that the service account can write to the project and intended browser cache during installation and can read and execute the browser at runtime. If a deployment switches users between those stages, test as both accounts and compare their HOME values.
Install Puppeteer and confirm its browser download
Install Puppeteer in the project, then explicitly ask its browser manager to install the compatible browser:
npm install puppeteer
npx puppeteer browsers installThe Puppeteer installation flow normally downloads a compatible Chrome for Testing build under $HOME/.cache/puppeteer. Some package managers or deployment environments block dependency lifecycle scripts. In that case, npm may install the package without the browser download, and a later launch can fail with Could not find Chrome (ver. …). Running npx puppeteer browsers install is the documented repair for a missing 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 errorsWhen the service runs under a different account, choose a cache location deliberately rather than relying on the installing user’s default. For example, configure a shared writable path with PUPPETEER_CACHE_DIR, ensure the runtime account has read and execute access, and then install the browser with that setting in effect:
Rank #2
export PUPPETEER_CACHE_DIR=/var/cache/my-service/puppeteer
mkdir -p "$PUPPETEER_CACHE_DIR"
npx puppeteer browsers installUse a directory your deployment policy permits; the example path is not a required CentOS location. Keep the same cache setting for the process that launches Puppeteer. If you change the cache after downloading Chrome, run the browser install command again so the new location contains the browser.
To see whether a browser file exists in the default cache, you can inspect it with:
find "$HOME/.cache/puppeteer" -type f -name chrome -print 2>/dev/nullIf the result is empty, do not assume a system browser is installed or silently substitute one: check the install output, cache configuration, effective user, and architecture. Use the Puppeteer browser-install command to put its expected browser in the configured cache.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Install CentOS 7 libraries and fonts
Chrome’s shared-library and font requirements are operating-system dependencies, not npm dependencies. Puppeteer’s CentOS troubleshooting list names these packages:
yum install -y
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-utils
yum update nss -yPackage availability can vary with enabled repositories and architecture. If yum reports a package as unavailable, retain the exact error and check the repository and architecture rather than swapping in unrelated packages. The command above uses the package names from Puppeteer’s CentOS guidance; a successful yum transaction does not by itself prove that Chrome’s dependencies are all resolved.
Use ldd to identify unresolved shared libraries
Run the dependency check against the downloaded Chrome executable, not against the Puppeteer JavaScript package:
ldd /path/to/chrome | grep notReplace /path/to/chrome with the actual executable path in the browser cache. An empty result means this check found no unresolved shared-library entries. It does not prove that the browser has correct permissions, can use a sandbox, has suitable fonts, or can load the target page.
If output contains a line ending in not found, record the missing library name and resolve it through the CentOS repositories available to the host. After installing the relevant dependency, rerun ldd. Avoid guessing from the launch symptom alone: this check narrows the issue to shared libraries, while sandbox and cache failures require separate investigation.
Launch Puppeteer with a real sandbox where possible
Chrome’s sandbox is a security boundary. Puppeteer documents that if there is no good sandbox for Chrome to use, Chrome can crash with No usable sandbox!. Prefer configuring a usable Linux sandbox and running Chrome as a non-root service user. Check the host’s sandbox setup and account privileges instead of treating missing libraries or a missing browser as a sandbox problem.
If the environment cannot provide a sandbox and the page content is fully trusted, the narrowly scoped fallback is to pass --no-sandbox to that launch:
const browser = await puppeteer.launch({
args: ['--no-sandbox'],
});Puppeteer strongly discourages running without a sandbox. This flag changes Chrome’s security boundary; it is not a general-purpose installation repair and should not be used for arbitrary or untrusted URLs. Prefer fixing the host’s sandbox configuration or moving the workload to a supported host.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Minimal Puppeteer smoke test
After installing the browser and dependencies, use a small script to distinguish a launch failure from a page-navigation failure. Save this as check-puppeteer.js in the project where Puppeteer is installed:
const puppeteer = require('puppeteer');
(async () => {
let browser;
try {
browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log('Title:', await page.title());
} catch (error) {
console.error(error);
process.exitCode = 1;
} finally {
if (browser) await browser.close();
}
})();Run it with node check-puppeteer.js as the production service account and with the same environment variables used by the service. If puppeteer.launch() fails, focus on browser discovery, libraries, permissions, and sandboxing. If launch succeeds but navigation fails, the installation has progressed further; inspect the navigation error and target-site or network conditions separately.
Troubleshoot by the exact error
| Symptom | Likely cause | Next action |
|---|---|---|
Could not find Chrome (ver. …) |
The browser postinstall download was blocked, the cache was moved, or the runtime user differs from the installer. | Run npx puppeteer browsers install; check HOME and PUPPETEER_CACHE_DIR; reinstall after changing the cache setting, and verify runtime read/execute access. |
Chrome exits immediately; ldd shows not found |
One or more shared libraries are missing. | Install the listed CentOS dependencies, capture any yum errors, and rerun ldd. |
No usable sandbox! |
The host cannot provide a suitable Chrome sandbox, or its privilege configuration is unsuitable. | Configure a real sandbox and run as a non-root user; consider the no-sandbox fallback only for fully trusted content when no sandbox can be provided. |
| Text appears as squares or is absent | Required font or X11 font packages may be missing. | Install the listed X11 and font packages, then retest the pages whose text rendering matters. |
| Node module-resolution or runtime-feature errors | The Node.js release may not be supported by the Puppeteer version. | Move to a maintained Node.js release supported by that Puppeteer version, then reinstall and rerun the smoke test. |
| Works in a shell but fails as a service | The service may use a different account, HOME, cache path, permissions, or environment. |
Repeat the user, home, cache, and permission checks in the service’s real runtime context. |
Make the repair reproducible, then plan to leave CentOS 7
A one-off fix is fragile if browser downloads, runtime users, and cache paths differ between deployment stages. For repeatable deployments, record the Node.js and Puppeteer versions you use, make the browser-install step explicit, set the cache location consistently, and verify that the runtime account can access it. Preserve the output from yum and ldd so a future deployment can distinguish repository or package changes from application changes.
CentOS Linux 7 reached end of life on June 30, 2024. The CentOS Project records that lifecycle date; Red Hat says CentOS 7 updates ended on that date and describes migration to RHEL, with optional extended support, as continuity options. A repaired Puppeteer installation on CentOS 7 does not restore operating-system updates. Treat it as an interim repair and plan a migration to a maintained operating system; where the organization needs enterprise continuity, evaluate the support and migration options directly with Red Hat.
Best Value
When comparing a local repair with migration or enterprise continuity, weigh four things: whether Chrome’s sandbox remains enabled, whether browser and cache setup is reproducible, how long the host remains on an end-of-life system, and who owns operating-system maintenance. Disabling the sandbox is the least attractive security trade-off; repeated local repairs do not change CentOS 7’s lifecycle status.
Or skip the browser setup
If your goal is to capture a website rather than run a browser on CentOS 7, ScreenshotNeo is a hosted website screenshot API and MCP server from Yorker Media. A single request can return a PNG, JPEG, WebP, or PDF. Its cleanup steps can accept consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with verdict and billing information in response headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
For a direct image capture, use the API call below. Replace YOUR_API_KEY with your key and change the target URL as needed. See the ScreenshotNeo API documentation for options and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo’s Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan. If this replaces a CentOS-hosted capture job, verify that the API’s output format and capture options fit your application before switching production traffic.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does an empty ldd result prove Puppeteer is fully fixed?
No. It only indicates that this shared-library check found no unresolved entries; browser access, sandbox setup, fonts, and page loading need their own checks.
Should I use --no-sandbox to fix Puppeteer on every CentOS 7 server?
No. It weakens Chrome’s security boundary and is only a last-resort option for fully trusted content when the host cannot provide a sandbox.
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.
