If Setup or Browser Tests Get Stuck

Most setup problems come from Node.js, the local configuration file, or the one-time browser download for end-of-epic tests. For any of them, you can also paste the error into the chat and ask Claude to fix it.

Setup problems

Problem	What to do
”node is not recognized”, or Windows keeps asking which app should open `node`	Install Node.js 22 or later from nodejs.org, fully close and reopen VS Code, then run `/start` again
”Module not found” errors after cloning	Ask Claude: “I’m seeing module not found errors. Can you fix my dependencies?”
Port 3000 is already in use	Another program is using the port. Ask Claude: “Port 3000 is already in use. Can you free it up?”
The dev server won’t start	Ask Claude: “My dev server won’t start. Here’s the error:” and paste the error

If web/.env.local isn’t being read

Check each of these:

The file is named exactly .env.local, not .env.local.txt or .env.
It’s inside the web/ folder, next to package.json.
You restarted the dev server after creating or changing it.
The variable names are spelled correctly. They’re case-sensitive.

If the browser download stalls

End-of-epic tests run in a copy of Chromium (about 130 MB). Claude downloads it in the background the first time you run /start, so it’s usually ready before the tests need it. If the download isn’t finished when the tests are due, the workflow waits for it.

The download has no progress bar, so a working download can look frozen. Keep working while it finishes.

If it seems stuck at 100%, it’s unpacking the browser and fetching a second, smaller file. Neither shows progress. On a virtual machine this can take up to five minutes. Don’t cancel it partway: a half-finished install leaves a lock that makes the next attempt stall straight away.

If it never finishes:

System	Likely cause	Fix
Linux (most virtual machines)	A company network or proxy is blocking the second download, or the disk is full	Set your proxy (see below) and check for free disk space. If an earlier attempt was cancelled, clear the cache with `rm -rf ~/.cache/ms-playwright` and install again.
Windows	Antivirus is scanning each unpacked file	Add `%USERPROFILE%\AppData\Local\ms-playwright` to your antivirus exclusions, or pause it for the install, then install again

Installing the browser yourself

Run this from the project folder:

cd web && npm run test:e2e:install

This command is the official installer. There’s no web page to download the browser from.

On Linux, if the browser installs but won’t launch and the error mentions a missing library such as libnss3.so, install the system libraries once. This needs admin rights:

cd web && sudo npx playwright install-deps chromium

Behind a proxy, point the installer at it, then run the install again:

# macOS or Linux
export HTTPS_PROXY=http://your-proxy:port

# Windows PowerShell
$env:HTTPS_PROXY="http://your-proxy:port"

On a fresh virtual machine each time, the browser lives outside your project folder, so every new machine downloads it again. Install it once and save it in your virtual machine image or snapshot.

For more detail, see the Playwright browsers documentation.