apify run: detect Playwright base image + missing local browser, direct user to remote or Docker fallback

[DaveHanns]

Problem

When an Actor's Dockerfile starts with FROM apify/actor-node-playwright* (any of the Playwright base-image variants — chromium, firefox, playwright), the Actor is authored assuming the Playwright browsers are pre-installed in that image. If the user runs apify run on their local machine and their local machine does not have the matching browsers installed, the Actor fails inside the child process with a stack trace like:

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

    npx playwright install

This is confusing because:

1. The Actor works perfectly when pushed to Apify — the base image has the browsers.
2. Running npx playwright install locally is not obviously the right fix — it downloads ~500 MB of browsers into the user's home directory outside the project. Users who intended to develop the Actor primarily via apify push && apify call don't want that footprint locally, and even after installing, subtle drift between local browser build + linux base-image browser build can cause its own bugs.
3. The CLI doesn't currently give any hint that the failure is base-image-related.

Proposed behavior

Before launching the child process in apify run, detect:

1. Actor's Dockerfile FROM line matches apify/actor-node-playwright (any tag).
2. Local Playwright browser binary is missing — e.g. require.resolve('playwright') succeeds but the browser cache directory (~/.cache/ms-playwright on Linux/macOS, %USERPROFILE%\\AppData\\Local\\ms-playwright on Windows) has no matching browser.

If both are true, refuse the local run with a message like:

This Actor uses the apify/actor-node-playwright base image, which pre-installs Playwright
browsers in the remote runtime. Your local machine does not appear to have Playwright
browsers installed.

Choose one of the following:

  1. Run the Actor remotely (recommended for Playwright Actors):
       apify push && apify call

  2. Install Playwright browsers locally (~500 MB download):
       npx playwright install

  3. Run the Actor's Docker image locally (requires Docker Desktop):
       apify run --docker         # not yet implemented — see below

The third option — apify run --docker — would build/run the Actor's Dockerfile locally, using the same image as production. This is optional as part of the same PR and could be a follow-up.

Files

• src/commands/run.ts — add a preflight check after useCwdProject resolves. Parse ./Dockerfile (already ubiquitous in Apify Actor projects), look at first FROM directive, match /^apify\\/actor-node-playwright/, then check for browser cache presence.
• Consider a --docker flag on run for the fallback execution mode.

Reproducer

apify create test-playwright --template ts-crawlee-playwright-chrome
cd test-playwright
# Without ever running `npx playwright install`:
apify run

Observe: run fails deep in the Actor with an opaque "Executable doesn't exist" error from Playwright, rather than a CLI-level guidance message.

Priority

Medium. It's not a correctness bug — the Actor itself works when pushed. But it's a common paper-cut for users developing Playwright Actors locally, and the current failure mode wastes time on a fix (npx playwright install) that isn't necessarily what the user wants.

---

Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.