Troubleshooting

Installation

browserType.launch: Executable doesn't exist

Cause: Playwright’s npm package doesn’t bundle a Chromium binary — it has to be downloaded separately, once per machine.

Fix:

npx playwright install chromium

Node version errors on install

Cause: frontend-qa requires Node ≥ 20 (engines.node across every package in the monorepo).

Fix: Upgrade Node, or use a version manager (nvm, fnm) to switch to 20+ for this project.

Running scan

Exit code 2, “no running or launchable dev server found”

Cause: No --url was given, nothing answered on 127.0.0.1:{5173,3000,4173,8080}, and detectProject() couldn’t find a dev script to launch (or the project isn’t a detected Vite/Next project).

Fix: Start your dev server first, or pass --url explicitly:

frontend-qa scan --url http://localhost:5173

Scan times out on every route

Cause: The default --timeout is 30000ms; a slow first compile (cold Vite/webpack cache) or a route that never reaches network-idle can exceed it.

Fix: Increase the timeout, or check the route loads normally in a regular browser first:

frontend-qa scan --url http://localhost:5173 --timeout 60000

--viewport rejected

Cause: The flag only accepts the exact WIDTHxHEIGHT format (e.g. 1280x800) — anything else fails a regex check before the scan starts.

Fix: Match the format exactly, digits only, one lowercase x.

Scan exits non-zero in CI even though the app “looks fine”

Cause: --fail-on defaults to high — any high or critical issue (a console error, a failed request) fails the run by design.

Fix: This is usually working as intended — check the printed issue list. If you want CI to be advisory only, use --fail-on never (the run still writes a report; it just never fails the process).

static and bundle

static reports “unresolved import” for a path that clearly exists

Cause: Unresolved-import detection does a filesystem existence check on relative imports; path aliases (e.g. @/components/... resolved via tsconfig.json paths) or non-relative imports resolved by a bundler aren’t followed the same way.

Fix: If this produces a false positive for your alias setup, treat it as a known limitation rather than a real dead import — check the path resolves via your bundler/tsconfig before treating the finding as actionable.

bundle --dir finds nothing

Cause: --dir must point at your actual build output (e.g. dist, dist/assets, .next) — it isn’t inferred from your framework.

Fix: Run your production build first, then point --dir at the output:

npm run build
frontend-qa bundle --dir dist

MCP server

A tool other than run_scan says “No report found”

Cause: get_report/get_issues/get_console_errors/get_screenshot all read an already-written report.json — they never trigger a scan themselves.

Fix: Call frontend.run_scan first, or pass runId/outDir pointing at a report produced by the CLI.

Didn’t find your issue?

Check FAQ, or see Contributing for how to report one. This page only documents failure modes traceable to the current source, config schema, and security model — see docs/SECURITY.md in the repository for the full threat model.