Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Puppeteer cannot start Chrome on a Linux server

ErrorError: Failed to launch the browser process!

Short answer

Puppeteer prints the real reason below the first line, so read that. On servers it is nearly always one of four things: Chrome is missing system libraries, the sandbox cannot start (root user or Ubuntu AppArmor), the downloaded browser is not where Puppeteer looks, or the container has no writable folders.

  • Applies to Node.js 22, Puppeteer 24, Ubuntu 24.04, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the browser binary on its own and read the message. It shows missing libraries or sandbox errors far more clearly than the Node stack trace.

    npx puppeteer browsers list
    ldd "$(find ~/.cache/puppeteer -name chrome -type f | head -n 1)" | grep "not found"
  2. 2Match what you see, then jump to its fix

    1. 1error while loading shared libraries, or ldd prints lines ending in not foundChrome is missing shared libraries on the serverFix
    2. 2No usable sandbox! in the launch outputThe sandbox cannot start: root in Docker or Ubuntu AppArmorFix
    3. 3Could not find Chrome, or the browser was never downloaded during installThe browser is not where Puppeteer looks for itFix
    4. 4chrome_crashpad_handler: --database is requiredA read-only container has nowhere for Chrome to writeFix

What does the error look like?

  • Error: Failed to launch the browser process!
  • error while loading shared libraries: libnss3.so: cannot open shared object file
  • No usable sandbox!
  • Could not find Chrome
  • Could not find expected browser locally
  • chrome_crashpad_handler: --database is required

Cause 1 of 4

Chrome is missing shared libraries on the server

1Check

A minimal server image has no graphics or font libraries. The troubleshooting guide's check is to run ldd on the chrome binary and grep for not.

ldd ~/.cache/puppeteer/chrome/*/chrome-linux64/chrome | grep not

2Fix

Install the packages that provide each missing library, then run again. Package names depend on the distribution; install what the ldd output names.

sudo apt-get update
sudo apt-get install -y libnss3 libatk-bridge2.0-0 libgbm1 libasound2

3Verify

ldd prints nothing for not found and a screenshot script works.

node -e "require('puppeteer').launch().then(b=>b.close()).then(()=>console.log('ok'))"

Confirmed by pptr.dev

Did this fix it?

Cause 2 of 4

The sandbox cannot start: root in Docker or Ubuntu AppArmor

1Check

Chrome should run sandboxed. On Ubuntu 23.10 and later an AppArmor policy blocks user namespaces for the Chrome for Testing build that Puppeteer downloads, and containers running as root hit the same wall.

id -u
cat /proc/sys/kernel/apparmor_restrict_unprivileged_userns

2Fix

In Docker, create a non-root user and run Node.js as that user, which is the pattern in the Puppeteer troubleshooting guide's Dockerfile example. For the AppArmor case, follow the Chromium user namespace guidance the troubleshooting page links to. --no-sandbox is a last resort for content you fully trust.

RUN groupadd -r pptruser && useradd -r -g pptruser -m pptruser
USER pptruser

3Verify

The launch succeeds without passing --no-sandbox.

docker run --rm my-image node -e "require('puppeteer').launch().then(b=>b.close()).then(()=>console.log('ok'))"

Confirmed by pptr.dev

Did this fix it?

Cause 3 of 4

The browser is not where Puppeteer looks for it

1Check

Browsers download to ~/.cache/puppeteer by default. A different user, a cached node_modules or a package manager that skips postinstall scripts leaves the folder empty.

ls ~/.cache/puppeteer
echo $PUPPETEER_CACHE_DIR

2Fix

Install the browser explicitly, or put it in a folder the runtime user can read, and use the same variable when running the app.

npx puppeteer browsers install chrome
# or a fixed folder
PUPPETEER_CACHE_DIR=/opt/pptr npx puppeteer browsers install chrome

3Verify

browsers list shows the installed version.

npx puppeteer browsers list

Confirmed by pptr.dev

Did this fix it?

Cause 4 of 4

A read-only container has nowhere for Chrome to write

1Check

A read-only root filesystem leaves Chrome without a config or cache folder.

docker inspect --format '{{.HostConfig.ReadonlyRootfs}}' my-container

2Fix

Point the XDG folders at a writable path such as /tmp, and give Puppeteer a writable userDataDir if needed.

ENV XDG_CONFIG_HOME=/tmp/.chromium
ENV XDG_CACHE_HOME=/tmp/.chromium

3Verify

The container launches the browser again.

docker run --read-only --tmpfs /tmp my-image node app.js

Confirmed by pptr.dev

Did this fix it?

How do I stop it coming back?

  • Install the browser during the image build, not when the app first starts.
  • Run the app as a non-root user in containers.
  • Pin the Puppeteer version so the Chrome it downloads matches what you tested.
  • Close the browser in a finally block so crashed jobs do not leave Chrome processes behind.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Puppeteer cannot start Chrome in an Alpine Docker image

Could not find expected browser locally

On Alpine, the Chrome that Puppeteer downloads does not run, and a hard-coded path such as /usr/bin/chromium-browser points at nothing if Chromium is not installed there.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.