Puppeteer cannot start Chrome on a Linux server
Error: 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
error while loading shared libraries, or ldd prints lines ending in not foundChrome is missing shared libraries on the serverFix - 2
No usable sandbox! in the launch outputThe sandbox cannot start: root in Docker or Ubuntu AppArmorFix - 3
Could not find Chrome, or the browser was never downloaded during installThe browser is not where Puppeteer looks for itFix - 4
chrome_crashpad_handler: --database is requiredA read-only container has nowhere for Chrome to writeFix
- 1
What does the error look like?
Error: Failed to launch the browser process!error while loading shared libraries: libnss3.so: cannot open shared object fileNo usable sandbox!Could not find ChromeCould not find expected browser locallychrome_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 not2Fix
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 libasound23Verify
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
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_userns2Fix
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 pptruser3Verify
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
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_DIR2Fix
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 chrome3Verify
browsers list shows the installed version.
npx puppeteer browsers listConfirmed by pptr.dev
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-container2Fix
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/.chromium3Verify
The container launches the browser again.
docker run --read-only --tmpfs /tmp my-image node app.jsConfirmed by pptr.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
Node.js request fails with getaddrinfo EAI_AGAIN
errno: -3001, code: 'EAI_AGAIN', syscall: 'getaddrinfo'
EAI_AGAIN means the system resolver asked a name server and got a temporary failure back.
3 causes, each with a fixBack end
Node.js https request fails with getaddrinfo ENOTFOUND
getaddrinfo ENOTFOUND
ENOTFOUND means the name lookup failed before any connection was made.
3 causes, each with a fixBack end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack 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 fixBack end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fix