How to Fix Puppeteer Chromium Startup Failures with Phusion Passenger

Start with the exact launch error, not Passenger itself. A Node.js app managed by Phusion Passenger can fail before Puppeteer runs, or Puppeteer can start while its Chromium child process fails because the browser is missing, shared libraries are unavailable, the sandbox cannot initialize, or the Passenger runtime user cannot read or write required paths. Capture the complete application and browser stderr, then follow the matching branch below.

Identify which startup stage is failing

Passenger is the process launcher; Chromium is a separate child process with its own installation, dynamic-linker, filesystem, kernel and security requirements. Classify the symptom before changing configuration:

#	Preview	Product	Price
1		The Chromium Connection: A Lesson in Nutrition	$214.57	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

Keep the full error, Puppeteer version, browser revision, Linux distribution or container image, Passenger version, effective Unix user and launch options. There is no single Passenger-specific fix that applies to every deployment.

1. Verify Passenger starts the intended Node.js file

Passenger uses app.js as the conventional Node.js startup file. Express-generator applications commonly start through bin/www. A wrong file can make it appear that Puppeteer is broken when the code that launches it never executes.

#1 Best Overall

The Chromium Connection: A Lesson in Nutrition

• Used Book in Good Condition

$214.57

Buy on Amazon

1. Confirm the Passenger application root is the directory containing your deployed package.json and startup file.
2. Set the application type to Node.js in Passenger’s configuration.
3. Set startup_file to the real relative path, such as app.js or bin/www. A custom filename must be configured explicitly.
4. Restart the Passenger application and check the new startup log before testing Chromium.

See Passenger’s configuration reference and Node.js deployment guide for the directives used by your deployment mode.

2. Confirm Puppeteer installed a browser

Puppeteer normally downloads a compatible Chrome for Testing browser during package installation. Deployment policies that disable package scripts, or builds that install dependencies in one environment and run them in another, can leave the deployed process without that browser.

1. Inspect the deployment output for Puppeteer’s browser-download step.
2. Check the Puppeteer cache directory and verify that the expected Chrome executable exists.
3. Run the check as the same Unix account Passenger uses, not only as root or your SSH login.
4. If you deliberately manage Chrome separately, verify the configured executablePath points to an existing executable.

Puppeteer documents executablePath, but guarantees operation only with its bundled browser. An externally installed Chrome or Chromium may require matching the Puppeteer release, browser revision and operating-system dependencies. The installation guide is at puppeteer installation documentation; launch options are described in the LaunchOptions reference.

Use a minimal diagnostic launch

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    dumpio: true
  });
  console.log('Chromium started');
  await browser.close();
})().catch(error => {
  console.error(error);
  process.exit(1);
});

Run this from the deployed application directory under Passenger’s runtime identity. dumpio forwards browser stderr, which distinguishes a missing executable from a linker or sandbox failure.

Rank #2

Chromium Picolinate: Everything You Need to Know

$7.63

Buy on Amazon

3. Check Linux shared libraries on the real host

A successful npm install does not prove that the Passenger host has every system library Chromium needs. Puppeteer’s troubleshooting guide recommends running the dynamic-linker check against the actual Chrome executable:

ldd /path/to/chrome | grep not

Replace the path with the executable Puppeteer is really launching. Any output indicates unresolved libraries. Install the corresponding packages for the exact distribution and browser revision, then rerun the command. Package names differ between Debian-family, Red Hat-family and container images; do not copy a dependency list from another base image without checking current browser requirements. Puppeteer’s living guidance is Troubleshooting.

Container and deployment checks

• Ensure the final runtime image, not only the build image, contains the libraries.
• Do not assume a browser copied from a different distribution is compatible with the runtime image.
• Retest after every image or package change so the next error identifies the next missing layer.

4. Treat sandbox errors as a separate problem

If stderr contains No usable sandbox!, investigate the host’s sandbox support rather than adding random flags. Puppeteer documents an AppArmor interaction on Ubuntu 23.10 and later that can affect Chrome for Testing user namespaces. Compare the host kernel, user-namespace settings and AppArmor policy with the guidance in the troubleshooting document and its linked Chromium instructions.

Puppeteer states: “Running without a sandbox is strongly discouraged.” Do not make --no-sandbox the routine production remedy. It reduces isolation and should be considered only when the page content is absolutely trusted and the operator accepts the security consequences. Restoring a functioning sandbox is safer than treating the flag as an equivalent fix.

Rank #3

The Chromium Program

$14.49

Buy on Amazon

5. Reproduce as Passenger’s Unix user

Passenger’s user-switching documentation requires the runtime account to read application files and write logs. Chromium adds more paths to verify: Puppeteer’s browser cache, the executable, temporary files and any user-data directory or profile you specify.

1. Identify the effective Passenger application user from your web-server or Passenger configuration.
2. As that user, test read and execute access to the application, cache and Chrome binary.
3. Test write access to the configured log, temporary and profile directories.
4. Remove stale profiles or choose a dedicated writable profile directory if concurrent processes share one.

A shell test as an administrator is not conclusive if Passenger runs under another account. Consult Passenger’s Unix user sandboxing guide for the permission model.

6. Change one layer, then restart and retest

Restart the Passenger application after each change and preserve the new log. A disciplined sequence prevents masking the original fault:

1. Correct the entry point and application type.
2. Confirm the bundled browser download or a valid external executable path.
3. Resolve every ldd “not found” result.
4. Investigate sandbox and AppArmor policy.
5. Fix ownership and permissions for the Passenger user.
6. Only then tune launch options, timeouts or profiles.

If the failure remains, report the exact error together with the versions, runtime user, host image and launch options. Documentation describes these failure categories, but does not establish one universal working recipe for all Passenger installations.

Rank #4

Nickel and chromium plating

$92.12

Buy on Amazon

Common errors and targeted fixes

Or skip the browser setup

For a one-off website image or an automated capture service, ScreenshotNeo can avoid maintaining Chromium inside Passenger. Its API accepts one GET request and returns PNG, JPEG, WebP or PDF. Cookie and consent banners, newsletter popups and chat widgets are removed before capture; bot checks, blank pages, failed loads and timeouts are not billed, and response headers identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

cURL (options and documentation: ScreenshotNeo docs):

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
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}`);

The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Is Passenger itself incompatible with Puppeteer?

No. Passenger launches the Node process; compatibility depends on the process environment and Chromium’s own requirements.

Should I always install system Chromium?

No. Puppeteer recommends its downloaded compatible browser; an external browser is an option with a validated executable path, but compatibility is not guaranteed.

Best Value

The Chromium Diet, Supplement and Exercise Strategy

• Used Book in Good Condition

$17.95

Buy on Amazon

Can I fix every failure by adding --no-sandbox?

No. It weakens isolation and does not fix missing binaries, libraries, permissions or an incorrect Passenger entry point.

Frequently Asked Questions

Is Passenger itself incompatible with Puppeteer?

No. Passenger launches the Node process; compatibility depends on the process environment and Chromium’s own requirements.

Should I always install system Chromium?

No. Puppeteer recommends its downloaded compatible browser; an external browser is an option with a validated executable path, but compatibility is not guaranteed.

Can I fix every failure by adding –no-sandbox?

No. It weakens isolation and does not fix missing binaries, libraries, permissions or an incorrect Passenger entry point.

The Bottom Line

Fix the failing layer in order: Passenger entry point, browser availability, shared libraries, sandbox policy, then runtime-user permissions. The exact stderr message and the environment in which Passenger runs determine the correct remedy.

Quick Recap

Bestseller No. 1

The Chromium Connection: A Lesson in Nutrition

Used Book in Good Condition

$214.57

Bestseller No. 2

Chromium Picolinate: Everything You Need to Know

$7.63

Bestseller No. 3

The Chromium Program

$14.49

Bestseller No. 4

Nickel and chromium plating

$92.12

Bestseller No. 5

The Chromium Diet, Supplement and Exercise Strategy

Used Book in Good Condition

$17.95

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.