Troubleshooting

This page collects the spots people most often stop at. Find the entry that matches what you are seeing and follow the notes underneath. If your symptom is not on the list, copy the error message verbatim into Claude Code and ask “how do I fix this?” — a next thing to try usually comes back.

The test result wobbles from run to run

If the same test passes sometimes and fails other times, it is flaky. The most common cause is the test acting before the screen has fully painted.

If the code holds an arbitrary timed wait (a hard sleep, something like waitForTimeout), that is the number-one cause of flakiness. It passes on a fast machine and fails on a slow one. Do not fix this by hand — tell the AI “this test has a hard sleep in it and it’s wobbling. Switch it to wait automatically until the screen is ready.”

If flakiness gets caught twice in validation and reaches blocked, you work it out with /recover-from-blocked in When the AI gets stuck.

The Playwright browsers are not installed

You ran a test on the web or electron track and see something like “browser not found” or “Executable doesn’t exist.” The actual browser the tests launch has not been downloaded yet.

pnpm exec playwright install --with-deps chromium

That one line pulls it down. The first time it is a large download and takes a few minutes. If it gets blocked on the network, try again in a moment. The base’s init.sh runs this line automatically too, but if it broke off partway, run it by hand once more.

The browser binaries are not cached in CI either — they get pulled fresh every time. Version drift causes nastier problems, so downloading them every time is the intended behavior.

The Maestro CLI is missing

On the mobile track you see “command not found: maestro.” Maestro is not installed yet.

curl -Ls "https://get.maestro.mobile.dev" | bash

After install, open a fresh terminal and maestro --version should print. If it installed but is still not found, the path did not make it into your shell startup file. Follow the guidance at the end of the install printout to add the path, then open a new terminal.

The test stops at the login step, or you see “401”, “403”, or “unauthorized.” Almost always .env.test.local is missing or empty.

First check that the file is there.

ls -la .env.test.local

If the file is missing, redo cp .env.test.example .env.test.local like number 6 in Prerequisites. If the file is there but values like the test account password are blank, fill them in.

After editing a value, you have to re-run the test for it to take effect. And the account you use here has to be a dedicated test account. Test with an account you actually rely on and that account’s data gets shaken.

The test cannot find a screen element

You see “locator not found,” “no element matches,” or “element is not visible.” The test could not find the button or input field it was trying to use. It is one of two things.

Your app’s screen changed, so that element disappeared or got a different name. This is a change on your app’s side, so the test has to be fixed to match.

Or the test finds the element by its position in the screen structure (CSS or XPath), so the smallest screen change makes it impossible to find. This base recommends finding elements by visible text or by role rather than by structural position. That holds up when the screen changes. Tell the AI “this selector depends on the screen structure and breaks. Switch it to find by visible text or role.” Giving the visible label on that element (for example, “Save”, “Log in”) makes it more precise.

Cannot reach the Electron main process

On the electron track, a test trying to click a dialog, a menu, or a tray icon gets stuck, or behavior on the main-process side does not register.

An Electron app’s native UI (the file-open dialog, the system menu, the tray) cannot be clicked directly by a test. That is a limitation. Instead, you write it as a stub of that behavior. This seat is hard for a non-developer to touch directly, so the fast route is to tell the AI “don’t click this dialog directly — switch it to a stub on the main-process side.” Fuller patterns are in the Expert manual.

If you run electron tests on local Linux and the window never appears and it hangs, it is because there is no display. You have to wrap it with xvfb-run.

Tests break in CI, or sharding goes wrong

If tests break differently in GitHub Actions than locally, it is usually an environment difference. Check that the browser installs fresh every time, and that the test environment variables are in GitHub’s secrets store. .env.test.local does not go up to git, so in CI those values have to be registered separately.

If sharding (splitting tests into pieces to run in parallel) goes wrong and only part of the results show, the step that merges the pieces’ results may be missing. This seat is outside non-developer territory, so start from the CI page in the Expert manual, or show the AI the workflow file and ask it to fix it.

Anything else

If nothing here matches, two more things to try.

First, copy the entire error message into Claude Code and type “fix this.” It usually points to a good next move. If you need more detail, .claude/state/last-run.log holds the full log of the last run.

If that still does not unstick it, open a GitHub issue or post in your team’s Slack. Include the same three things together.

Where you got stuck (which track, which flow, which command)
The full error message
Environment info (operating system, Node version, track and tool)

A stuck point where the AI workflow loops on the same spot twice belongs to When the AI gets stuck, not this page.