Playwright "Executable doesn't exist ... chromium_headless_shell" in CI

By Kaveh Alemi·Latchkey

Playwright resolves the browser from ~/.cache/ms-playwright/<browser>-<rev> and the directory is empty, so it tells you to run install. In CI this means the install step was skipped, ran for a different Playwright version, or the cache was restored under the wrong key.

What this error means

Tests fail immediately with "browserType.launch: Executable doesn't exist at .../chromium_headless_shell-XXXX/chrome-linux/headless_shell" and the hint "Looks like Playwright Test or Playwright was just installed".

browserType.launch: Executable doesn't exist at
/home/runner/.cache/ms-playwright/chromium_headless_shell-1148/chrome-linux/headless_shell
Looks like Playwright Test or Playwright was just installed or updated.
Please run the following command to download new browsers:
    npx playwright install

Diagnose it: browser, server, or timing?

End-to-end failures in CI are dominated by three causes that have nothing to do with the test: the browser binary is missing, the application under test is not listening yet, or the test raced the page. Establish which before reading the assertion.

# 1. are the browsers actually installed in THIS job?
npx playwright install --with-deps chromium
npx playwright --version

# 2. is the app up before the tests start?
npx wait-on http://localhost:3000 --timeout 60000

# 3. capture evidence for the failure you cannot reproduce
npx playwright test --trace on --video retain-on-failure

Common causes

The install step never ran in this job

A workflow that only runs npm ci installs the package but not the browser binaries; the launch then finds an empty cache directory.

A restored browser cache was built for a different version

Caching ~/.cache/ms-playwright by a stale key restores binaries for an old revision, so the path the new package expects is missing.

How to fix it

Run install after dependencies

1. Add a dedicated install step after npm ci.
2. Use --with-deps so OS libraries come too.
3. Run it on every job that launches a browser.

- run: npm ci
- run: npx playwright install --with-deps

Key the browser cache to the Playwright version

Include the installed Playwright version in the cache key so a version bump invalidates stale binaries.

- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

Make the browser cache safe

• Key the browser cache to the exact test-runner version. A cache restored from a different version gives you a binary that does not match the client and fails in a way that reads like a missing install.
• Install browsers after dependencies, not before; a dependency install can replace the package that owns the browser path.
• Prefer the vendor container image when the runner allows it. It removes the whole class of missing-system-library failures.

How to prevent it

• Always install browsers in CI, even when node_modules is cached.
• Tie any ms-playwright cache key to the lockfile so version bumps invalidate it.
• Run npx playwright install --dry-run to see which browsers are expected.

Frequently asked questions

Related guides

References

• GitHub Actions documentation