BackstopJS Puppeteer Chromium download / launch failed in CI

By Daniel Zoghalchali·Latchkey

BackstopJS relies on Puppeteer's Chromium. If the browser was not downloaded during install, or the runner lacks the shared libraries Chromium needs, the engine fails to launch and every scenario errors.

What this error means

Backstop fails with "Could not find Chromium" or "Failed to launch the browser process ... error while loading shared libraries: libnss3.so." No scenarios run because the engine never starts.

Error: Could not find Chromium (rev. 1108766). This can occur if either
1. you did not perform an installation before running the script, or
2. your cache path is incorrectly configured.

Common causes

Chromium skipped during install

A PUPPETEER_SKIP_DOWNLOAD flag, an offline install, or a cache mismatch left Puppeteer without a browser binary.

Missing shared libraries on a slim runner

Chromium needs libraries like libnss3, libatk, and fonts. A minimal base image omits them, so the browser cannot launch.

How to fix it

Ensure the browser is installed

Install the Puppeteer browser explicitly so a binary exists in the expected cache path.

npx puppeteer browsers install chrome

Install Chromium system dependencies

Add the shared libraries Chromium needs, or run Backstop in its Docker image which bundles them.

sudo apt-get update && sudo apt-get install -y \
  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libasound2

How to prevent it

• Do not set PUPPETEER_SKIP_DOWNLOAD in CI unless you provide a browser.
• Install Chromium system libraries in the runner image.
• Use the official BackstopJS Docker image, which bundles the engine.

Frequently asked questions

Related guides

References

• GitHub Actions documentation