阅读中文版本

Playwright Browser Executable Missing — Install Failed

Fix "Executable doesn't exist" by installing Playwright browsers and their OS dependencies, matching versions, and caching correctly in CI.

npx playwright install --with-deps chromium

npx playwright install --dry-run

Symptoms

This debugging guide addresses “Playwright Browser Executable Missing — Install Failed”. Start from the symptoms, follow the ordered diagnostics, and confirm each hypothesis before moving on; the fix and verification steps then close the loop.

Observed symptoms include:

• Playwright errors “Executable doesn’t exist at … chromium-…”
• Tests pass on a developer machine and fail in CI
• The error suggests running playwright install

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Install the browsers explicitly

npx playwright install --with-deps chromium

This downloads the binaries and their system dependencies, resolving the missing executable.

Step 2: Confirm the install path

npx playwright install --dry-run

The dry run prints the expected binary locations and versions, matching them to the error.

Likely contributors, in order of frequency:

• The browser binaries were not downloaded (fresh install or cache miss)
• A browser version bump invalidated a cached binary
• Missing OS libraries for the browser in a slim container

Root Cause

Playwright downloads browser binaries separately from the npm package, keyed by version. A fresh environment or a version bump without a matching download leaves no executable, so the runner cannot launch the browser.

The Fix

Run npx playwright install –with-deps in install steps, keep the browsers cache key aligned to the Playwright version, and install OS libraries when using slim base images.

Watch out: Caching browsers with a stale key reuses binaries from a different version and causes subtle launch failures; key the cache on the version.

# install browsers and OS deps
npx playwright install --with-deps

# GitHub Actions: cache keyed on the Playwright version
- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

- run: npx playwright install --with-deps chromium

Verify and Prevent

Run the test suite and confirm the browser launches and tests execute; verify the install step reports the expected version.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.