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

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') }}

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