Recommended Free Tools
When Puppeteer fails to start Chromium under Phusion Passenger, Passenger is usually only exposing an environment problem: the Node process may use the wrong entry file, the browser may not exist in the deployed cache, Linux libraries may be missing, Chrome’s sandbox may be unavailable, or Passenger’s Unix user may not be able to read or execute the required files. Fix the failure by identifying the stage at which it occurs, then test that layer using the same account and environment Passenger uses.
Start with the exact failure, not the word “Passenger”
Capture the complete Passenger/application log and Chromium’s stderr from the same launch attempt. The remedy depends on the message:
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
The Chromium Connection: A Lesson in Nutrition | $215.30 | Buy on Amazon |
| 2 |
|
Chromium Picolinate: Everything You Need to Know | $7.63 | Buy on Amazon |
| 3 |
|
The Chromium Program | $14.49 | Buy on Amazon |
| 4 |
|
Nickel and chromium plating | $92.12 | Buy on Amazon |
| 5 |
|
The Chromium Diet, Supplement and Exercise Strategy | $17.95 | Buy on Amazon |
| Observed stage | Likely class of problem | First check |
|---|---|---|
| Passenger application never starts | Wrong startup file, app type, syntax or dependency error | Passenger app_type, startup_file and Node logs |
| Node starts, but Puppeteer says “Could not find Chrome” | Browser download/cache was not deployed or the path is wrong | Installed browser and executablePath |
| Executable is found, then exits immediately | Missing shared libraries or incompatible system image | ldd output for the browser binary |
Stderr contains No usable sandbox! |
Kernel, user-namespace or security-policy restriction | Host sandbox and AppArmor configuration |
| Works in a shell but not through Passenger | Different Unix user, environment, permissions or writable paths | Repeat tests as Passenger’s effective app user |
Keep the Puppeteer version, browser revision, Linux distribution or container image, Passenger engine and version, runtime user, and launch options with the error report. There is no single Passenger-specific cause or universal configuration.
1. Confirm Passenger launches the intended Node application
Passenger’s Node.js convention is app.js. Applications generated by Express commonly start from bin/www. If your file has another name, configure the startup file explicitly and set the application type to Node.js.
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
- Used Book in Good Condition
What to verify
- The configured application root is the directory that contains
package.jsonand your startup file. app_typeis Node.js, not a different Passenger application type.startup_filepoints to a file that exists relative to the application root.- The startup file actually reaches the code that calls
puppeteer.launch().
Passenger’s configuration reference documents these settings and defaults: Passenger Standalone configuration reference. A wrong entry point can look like a Chromium failure because the browser-launching code never runs.
2. Verify that a compatible browser exists after deployment
Puppeteer normally downloads a compatible Chrome for Testing browser during package installation. A deployment can lose that browser when package-manager install scripts are disabled, dependencies are installed in a build environment whose cache is not copied to production, or the runtime account cannot read the cache.
Check the installation and cache
- Install dependencies using the same lockfile and deployment procedure used in production.
- Inspect the Puppeteer cache location and confirm that a Chrome for Testing executable is present.
- Check that the Passenger runtime user can traverse every parent directory and read and execute the browser file.
- Restart the Passenger application after correcting the deployment; do not rely on a shell process that has a different environment.
If Chrome is managed outside Puppeteer, pass its absolute path:
const browser = await puppeteer.launch({
executablePath: '/absolute/path/to/chrome'
});The executablePath option is supported, but Puppeteer states that operation is guaranteed only with its bundled browser. An externally installed Chrome or Chromium must therefore be kept compatible with your Puppeteer release. See the Puppeteer installation guide and LaunchOptions reference.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Make the browser path observable
Log the resolved path and the effective user at application startup, without printing credentials:
import os from 'node:os';
import puppeteer from 'puppeteer';
console.log({ user: os.userInfo().username, cwd: process.cwd() });
console.log('Puppeteer executable:', puppeteer.executablePath());If you use puppeteer-core, it does not manage a browser download; provide an explicit executable path and verify it during deployment.
3. Check shared libraries on the actual Passenger host
A browser file can exist and still fail before startup because the dynamic linker cannot load a required library. Run Puppeteer’s documented diagnostic against the exact Chrome executable:
ldd /absolute/path/to/chrome | grep notAny output indicates unresolved shared libraries. Install the corresponding runtime packages for the distribution and browser revision used by the deployed image, then rerun ldd until no libraries are reported missing. Package names differ between Debian/Ubuntu, CentOS/RHEL and other distributions, and Chrome requirements change; do not copy a package list intended for a different base image. Puppeteer’s troubleshooting guide links current dependency guidance: Puppeteer troubleshooting.
Container and release checks
- Run the diagnostic inside the production container or VM, not on your laptop.
- Ensure the final runtime image contains libraries installed only in a build stage.
- Check architecture (for example, x86_64 versus ARM) and that the browser binary matches it.
- After changing packages, restart Passenger so the new process sees the updated filesystem.
4. Treat “No usable sandbox!” as a separate security branch
Chrome can exit with No usable sandbox! when the host cannot provide a usable sandbox. Puppeteer documents an AppArmor interaction on Ubuntu 23.10 and later that can affect Chrome for Testing user namespaces. Inspect kernel/user-namespace support and the host’s AppArmor policy, then follow the guidance for your exact Ubuntu and Chrome revisions.
The Puppeteer project explicitly warns: “Running without a sandbox is strongly discouraged.” Do not make --no-sandbox your routine production fix. If the page content is absolutely trusted and your security owner accepts the reduced isolation, the temporary diagnostic is:
const browser = await puppeteer.launch({
args: ['--no-sandbox']
});This removes a browser security boundary; it does not repair the host sandbox. Document the exception, restrict the content and process permissions, and pursue a functioning sandbox or an approved isolation boundary instead. The relevant host-specific discussion is in the Puppeteer troubleshooting guide.
5. Reproduce as Passenger’s Unix user
Passenger’s user sandboxing means a successful administrator shell test is not conclusive. Passenger documents that the application user needs read access to application files and write access to logs. Chromium also needs access to its executable, cache, temporary directory and, when configured, a user-data/profile directory.
Rank #3
Permission checklist
- Identify the effective Unix user and group configured for the Passenger application.
- As that account, test that the application root and browser cache are traversable and readable.
- Verify the browser file has execute permission and that its interpreter and libraries are accessible.
- Use a writable, private temporary/profile directory; avoid a directory created only for an administrator.
- Confirm Passenger’s log directory is writable so the real browser stderr is not lost.
Passenger’s deployment and user-sandboxing documentation provides the surrounding permission model: Deploying a Node.js app and Sandboxing apps with Unix user accounts.
6. Use a minimal launch test before restoring application complexity
Remove application-specific options temporarily and prove that Passenger can start one browser and close it:
import puppeteer from 'puppeteer';
(async () => {
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await browser.close();
})().catch(error => {
console.error(error);
process.exitCode = 1;
});Run the same script through the deployed release and Passenger, changing one variable at a time. Once it works, reintroduce custom arguments, proxy settings, profiles and navigation code individually. This separates a browser startup defect from a later page-load or application exception.
Common errors and precise fixes
“Could not find Chrome” or an executable-not-found error
Cause: the Puppeteer browser download did not run, the cache was not included in the release, or the configured path is wrong. Fix the install/deploy process, expose the cache to the Passenger user, or set and validate an absolute executablePath. Check whether your package manager blocked install scripts.
ldd reports “not found”
Cause: missing runtime libraries in the production image. Install distribution-appropriate packages, verify architecture, and repeat the command against the exact binary Passenger launches.
No usable sandbox!
Cause: unavailable user namespaces or a security policy such as the documented Ubuntu 23.10+ AppArmor interaction. Repair host policy and kernel support. Use --no-sandbox only for absolutely trusted content with an explicit security decision.
Rank #4
Works over SSH, fails in Passenger
Cause: different user, PATH, home directory, cache, current directory, permissions or temporary paths. Log non-secret environment details, then repeat the checks as the Passenger account.
Passenger reports an application startup exception
Cause: wrong startup_file, missing production dependency, syntax error or code that throws before launch. Verify the entry point and run the minimal script in the deployed release before investigating Chromium.
Free tools Windows power users keep installed
One-click scans. No signup required.
Reliability, performance and cost considerations
- Keep browser installation deterministic with a lockfile and a deployment step that preserves the intended Puppeteer cache.
- Do not share one writable profile between concurrent browser processes; create isolated temporary or user-data directories.
- Close pages and browsers on every success and failure path to prevent Passenger workers accumulating Chrome processes.
- Record browser revision, Puppeteer version and host image in deployment metadata so upgrades can be correlated with failures.
- Changing hosts may alter libraries, namespaces or AppArmor behavior, but no provider change alone guarantees a fix.
Or skip the browser setup:
For a service that returns a screenshot without you maintaining Chromium under Passenger, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; failed loads, bot checks/CAPTCHAs, blank pages, timeouts and cache hits are not billed, with the result identified by X-Page-Verdict and X-Billed headers. Its MCP tools—take_screenshot, get_page_info and capture_pdf—let Claude, Cursor and other MCP clients request captures.
One GET request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the complete options and authentication details in the ScreenshotNeo documentation. You can also use its 63 options for full-page or CSS-element captures, device and viewport settings, dark mode, retina scale, PDF output, custom CSS/JavaScript, waits, blocking rules, headers, cookies, geolocation, signed links, asynchronous webhooks and bulk capture.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
Does Passenger itself download Chromium?
No. Passenger launches your Node application; Puppeteer or your deployment process must provide the browser and its dependencies.
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 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchIs an externally installed Chrome always supported?
Puppeteer supports selecting an executable path, but guarantees operation only with its bundled browser. Validate external browser compatibility for your exact versions.
Best Value
- Used Book in Good Condition
Should I add --no-sandbox to every Passenger deployment?
No. The Puppeteer documentation strongly discourages running without a sandbox. Investigate host namespaces and security policy first.
Why does a browser test pass as root but fail in production?
Passenger normally runs the app as another Unix user with different file, cache, temporary-directory and security-policy access. Test as that effective user.
Frequently Asked Questions
Can I fix every startup failure by reinstalling Puppeteer?
No. Reinstallation helps only when the browser download or dependency installation was the failing layer; library, sandbox, entry-point and permission errors require their corresponding fixes.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What information should I include when escalating the issue?
Provide the complete browser stderr, Passenger log, Puppeteer and browser versions, Linux image, runtime user, configured startup file, and launch arguments, while removing secrets.
The Bottom Line
Diagnose the failure stage first: entry point, browser availability, shared libraries, sandbox, or Passenger-user permissions. Correct that layer in the deployed environment, then retest with a minimal launch before restoring application options.
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.
