Reference
Troubleshooting
Why a step failed and how to fix it.
All documentation
Every failed run names a category, the step, and the expected and actual values. Start with the failure screenshot: it shows what the browser saw.
| Failure | What to do |
|---|---|
| Element not found | The locator matched nothing before the timeout. Check the role and accessible name in the browser's accessibility inspector, or use a label or test id. If the element appears late, the default 10 s wait is usually enough; raise the step timeout if not. |
| Matched N elements | Locators must match one element. Make the name more specific, scope by role, or set nth to first, last or an index. |
| Target not allowed | The page navigated to a host outside the allow list, such as a sign in provider. Add it to the environment's hosts (same site) or the project's third party hosts. |
| Requests blocked by the allow list | A script, API or font host is not allowed. The run lists the blocked hosts with a button to allow them. Blocked requests do not count as failed requests. |
| Uncaught page error | The page threw a JavaScript exception. The console tab shows it. If it comes from a third party script you do not control, add a substring of the message to checks.ignore. |
| Step timed out | The page did not reach the expected state in time. Look at the failure screenshot: is the page still loading, showing an error, or a cookie banner covering the button? |
| Visual difference | Compare the side by side and difference views. If the change is intended, accept the new baseline. If it is noise, mask the changing area or raise maxDiffRatio slightly. |
| Missing variable | The test references a variable or secret that the project does not define. Add it in the project settings. |
| Runner error | A problem on our side. It is refunded; run again. If it keeps happening, contact support with the run id. |
| Passes sometimes | Usually a race: a fixed pause instead of waiting for an element, or an assertion on data that changes. Wait for the specific element or response, and use random data for things you create. |
Still stuck? Contact support with the run id from the top of the run page.