Maaz Zindani

Loading the index…

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

Puppeteer cannot start Chrome in an Alpine Docker image

ErrorBrowser 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.

  • Applies to Puppeteer 24, Node.js 22, Alpine Linux 3.19, Docker
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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'
  2. 2Match what you see, then jump to its fix

    1. 1Browser was not found at the configured executablePathChromium is not installed in the image, or the path is wrongFix
    2. 2Could not find expected browser locally, or Puppeteer uses its own cached ChromeThe downloaded Chrome does not run on AlpineFix
    3. 3No usable sandbox!Chromium starts but the sandbox cannot be usedFix
    4. 4Timeouts at launch with Alpine 3.20A new Alpine release ships a Chromium that times outFix

What does the error look like?

  • Browser was not found at the configured executablePath (/usr/bin/chromium-browser)
  • Could not find expected browser locally
  • No 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-browser

3Verify

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

Did this fix it?

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

Did this fix it?

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 sandbox

2Fix

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 20

Confirmed by pptr.dev

Did this fix it?

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-release

2Fix

Pin the base image to the Alpine version that the docs say works, until the docs say otherwise.

FROM node:22-alpine3.19

3Verify

Rebuild and confirm the release file now reads 3.19.x.

docker build -t my-image . && docker run --rm my-image cat /etc/alpine-release

Confirmed by pptr.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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