Puppeteer cannot start Chrome in an Alpine Docker image
Browser was not found at the configured executablePath (/usr/bin/chromium-browser)Short answer
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. Install Chromium with apk, find its real path, give that path to Puppeteer as executablePath, and use the sandbox flag your container needs.
Fix it fast
1Find out which cause you have
Open a shell in the container and ask where Chromium really is. The path in your code must match this output exactly.
docker exec -it my-container sh -c 'ls -l /usr/bin/chromium*; which chromium chromium-browser'2Match what you see, then jump to its fix
- 1
Browser was not found at the configured executablePathChromium is not installed in the image, or the path is wrongFix - 2
Could not find expected browser locally, or Puppeteer uses its own cached ChromeThe downloaded Chrome does not run on AlpineFix - 3
No usable sandbox!Chromium starts but the sandbox cannot be usedFix - 4
Timeouts at launch with Alpine 3.20A new Alpine release ships a Chromium that times outFix
- 1
What does the error look like?
Browser was not found at the configured executablePath (/usr/bin/chromium-browser)Could not find expected browser locallyNo usable sandbox!
Cause 1 of 4
Chromium is not installed in the image, or the path is wrong
1Check
Puppeteer checks the file exists before it launches and throws this message when it does not. If ls shows nothing, the package is missing; if it shows a different file name, the path in your code is wrong.
docker exec -it my-container sh -c 'apk info -e chromium; echo $PUPPETEER_EXECUTABLE_PATH'2Fix
Install Chromium in the Dockerfile with apk and point Puppeteer at the file that the check printed. The Puppeteer troubleshooting page uses this pattern.
RUN apk add --no-cache chromium nss
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser3Verify
The file exists inside the rebuilt image.
docker run --rm my-image sh -c 'test -x "$PUPPETEER_EXECUTABLE_PATH" && echo ok'Confirmed by pptr.dev
Cause 2 of 4
The downloaded Chrome does not run on Alpine
1Check
The Puppeteer docs say Chrome does not support Alpine out of the box. Puppeteer's own download (stored in ~/.cache/puppeteer by default) is therefore not what you want in this image.
docker exec -it my-container sh -c 'ls ~/.cache/puppeteer 2>&1'2Fix
Use the system Chromium through executablePath. The docs set PUPPETEER_EXECUTABLE_PATH in the Dockerfile so Puppeteer does not rely on its own download.
const browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
});3Verify
Launch and print the browser version.
node -e "require('puppeteer').launch({executablePath: process.env.PUPPETEER_EXECUTABLE_PATH}).then(async b => { console.log(await b.version()); await b.close(); })"Confirmed by pptr.dev
Cause 3 of 4
Chromium starts but the sandbox cannot be used
1Check
In many container setups the sandbox cannot be created. The Puppeteer docs describe this error and say that running without a sandbox is strongly discouraged.
docker logs my-container 2>&1 | grep -i sandbox2Fix
Preferred: set up a usable sandbox as the troubleshooting page describes. Only for a trusted workload such as screenshots of your own pages, launch with the flag the docs show.
const browser = await puppeteer.launch({
args: ['--no-sandbox'],
});3Verify
The launch call returns a browser instead of throwing.
docker logs my-container 2>&1 | tail -n 20Confirmed by pptr.dev
Cause 4 of 4
A new Alpine release ships a Chromium that times out
1Check
The Puppeteer docs state that the Chromium in Alpine 3.20 causes timeouts and that Alpine 3.19 fixes it. Check your base image tag.
docker run --rm my-image cat /etc/alpine-release2Fix
Pin the base image to the Alpine version that the docs say works, until the docs say otherwise.
FROM node:22-alpine3.193Verify
Rebuild and confirm the release file now reads 3.19.x.
docker build -t my-image . && docker run --rm my-image cat /etc/alpine-releaseConfirmed by pptr.dev
How do I stop it coming back?
- Print the real Chromium path in the Dockerfile build with a RUN test -x line, so a wrong path fails the build, not the first request.
- Read executablePath from an environment variable, not a string inside the code.
- Pin the base image tag; do not use a moving alpine tag for a browser workload.
- Run the container as a non-root user and follow the sandbox guidance instead of leaving --no-sandbox on everywhere.
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 on a Linux server
error while loading shared libraries: libnss3.so: cannot open shared object file
Puppeteer prints the real reason below the first line, so read that.
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