Puppeteer PUPPETEER_SKIP_DOWNLOAD leaves no browser in CI

Setting PUPPETEER_SKIP_DOWNLOAD (or the older PUPPETEER_SKIP_CHROMIUM_DOWNLOAD) tells the post-install to not fetch Chromium. That is correct only if you point Puppeteer at a Chrome you install yourself; otherwise the launch has no executable.

What this error means

After npm ci, the launch fails with "Could not find expected browser" even though a cache step ran, because a .npmrc or CI env variable skipped the browser download.

Puppeteer

# .npmrc or environment
PUPPETEER_SKIP_DOWNLOAD=true
# later, at runtime:
Error: Could not find expected browser (chrome) locally.

Common causes

Skip-download set without an alternative browser

The flag prevents the bundled download, but no executablePath or system Chrome is provided, so the launch finds nothing.

A leftover skip flag from a Docker base image

A base image sets the skip variable to keep image size down; a job that relies on the bundled browser then fails.

How to fix it

Either install the browser or point at a system Chrome

Remove the skip flag and run npx puppeteer browsers install chrome, or
Keep the skip flag and install a system Chrome, then pass its path.
Confirm the launch uses that executable.

launch options

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/google-chrome-stable',
  args: ['--no-sandbox'],
});

Unset the skip flag for the test job

Clear the inherited variable so the normal browser download runs.

.github/workflows/ci.yml

env:
  PUPPETEER_SKIP_DOWNLOAD: ''

How to prevent it

Only set skip-download when you deliberately supply your own Chrome.
Document the executablePath your CI relies on next to the skip flag.
Audit base-image env vars for inherited Puppeteer skip settings.