Skip to main content

Troubleshooting

Startup​

No package.json found in <folder>.​

Watcher must run from the directory that contains your project's package.json, not from a subfolder such as tests/. Change to the project root and run npx watcher start again.

Watcher requires Node.js ^22.13.0 || >=24.0.0.​

Your Node.js version is unsupported. Install Node.js 22.13.0 or later in the 22.x line, or 24.0.0 or later. Node 23 is excluded. See Requirements.

Port 5050 is already in use.​

Another program, possibly another Watcher instance, uses the port. Choose another:

npx watcher start --port 5051

Invalid port: <value>.​

The port must be a whole number from 1 to 65535.

npx watcher runs the wrong program​

An unrelated npm package is called watcher. Install Watcher locally first:

npm install --save-dev @elixir-nexus/watcher@alpha

Project and scripts​

Health shows a Playwright warning​

@playwright/test is not installed or resolvable in this project. Install it in the project:

npm install --save-dev @playwright/test

Until then, scripts still run in Generic mode, but Playwright-aware runs and Playwright Tools are disabled.

A script I added does not appear, or settings look outdated​

Watcher reads scripts and configuration when it starts. Restart Watcher after changing package.json or your Playwright config. In the Run Planner, Refresh current settings re-checks the selected script.

My Playwright script runs in Generic mode​

Watcher shows the reason next to the script. See Script compatibility for the rules and fixes.

A run fails in Watcher but passes with npm run​

Playwright-aware runs start Playwright directly and do not set npm's npm_* variables or add node_modules/.bin to PATH. If your webServer or helper commands depend on those, select Run as Generic package script in Run options, or set the required environment before starting Watcher. See Differences from npm run.

A broken Playwright config​

If Playwright cannot load your config, the Run Planner shows the configuration as unavailable, and a run shows Playwright's own error in Live Output. Fix the config and select Refresh current settings.

Integration and progress​

No progress counters​

  • Generic runs never have structured progress.
  • On Playwright 1.62 or older, runs use Basic integration. Upgrade to Playwright 1.63+ for Enhanced progress.
  • Basic fallback means Watcher's reporter could not be resolved from your project. Install Watcher as a project dev dependency rather than globally.

See Playwright integration.

I added Watcher's reporter to my config by hand​

You do not need to. On Playwright 1.63+, Watcher adds @elixir-nexus/watcher/reporter automatically for its own runs. If your config also lists it, only one reporter instance sends progress, so counts are not duplicated. You can remove the manual entry; Watcher never edits your config for you.

Runs​

Stop Run stays on Stopping​

Watcher keeps the run in Stopping until it confirms the process tree has exited. If it does not finish, stop Watcher with Ctrl+C and check for leftover browser processes.

History​

Run history is unavailable or could not be read​

Runs continue to work without history, and Watcher preserves the existing database. Try, in order:

  1. Check that the project folder is writable and the disk has free space, then restart Watcher.
  2. If you recently downgraded Watcher, upgrade again. Older versions cannot read newer databases.
  3. To start fresh: stop Watcher, move or rename .watcher/watcher.db, then start Watcher again.

A run is missing from Recent Runs​

Recent Runs shows the ten most recent completed runs. A run might also be missing if Watcher was killed before saving it, or if the dashboard showed that it was not confirmed saved.

Reports and artifacts​

Content access unavailable on this platform/configuration​

Preview and download are unavailable on Windows and macOS in the Alpha. The references remain visible; open the files from your file system or with npx playwright show-report.

Current contents may belong to a later run​

Reporters usually reuse the same output location. Watcher shows what exists there now, not an archived copy.

Playwright Tools​

The tool opens no visible window​

Native window behavior is experimental. Expand Diagnostic output, select Stop tool, and report your environment.

Open UI Mode is disabled​

UI Mode cannot open while a managed run is active, or while another tool session is open. Wait for the run to finish or stop it first.

Still stuck?​

Ask on Discord or email support. See Support and feedback.