> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/debugging-tests/error-codes.md).

# Error codes

Every BugBug step error code explained: what it means, why it happens and how to fix it, including generic \<STEP>\_FAILED codes such as CLICK\_FAILED, how BugBug chooses the error after a timeout, and w

When a step fails, BugBug shows an error code and a message in the step's details in the [run history](https://docs.bugbug.io/debugging-tests/runs-history.md). The same code is returned as `errorCode` by the [Public API](https://docs.bugbug.io/integrations/public-api.md), the [CLI](https://docs.bugbug.io/integrations/cli.md) and the [MCP server](https://docs.bugbug.io/ai-testing/mcp.md).

{% hint style="info" %}
**In short**

* Most problems don't fail a step immediately. BugBug keeps retrying the step until its [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md), and then reports the last problem it saw.
* `ELEMENT_DOES_NOT_EXIST` and `FAILED_WAITING_CONDITIONS` are the most common codes. Start with the step's screenshot and its [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md).
* A code ending in `_FAILED`, such as `CLICK_FAILED` or `TYPE_FAILED`, means the element was found and the waiting conditions passed, but the action didn't finish before the timeout.
* Step errors give the run the **failed** status. **Error** means the run itself couldn't be completed, for example because the browser stopped responding.
  {% endhint %}

## How BugBug chooses the error

A step is retried until it succeeds or its timeout runs out. Some errors stop the step at once, without retrying:

* the test doesn't start with a Go to URL step (`MISSING_GOTO_STEP`),
* the step has no selector (`SELECTOR_REQUIRED`),
* the page couldn't be loaded (`PAGE_LOADING_ERROR`),
* the browser blocked BugBug on the page (`BLOCKED_BY_BROWSER_POLICY`),
* a visual regression step has no reference screenshot (`REFERENCE_SCREENSHOT_NOT_FOUND`).

When the timeout runs out, BugBug reports the first of these that applies:

1. The tab the step should run in is gone: `WINDOW_OR_TAB_DOES_NOT_EXIST`.
2. An error was reported during the retries: that error, for example `EVENT_DISPATCHED_ON_INVALID_ELEMENT` or `VARIABLE_DOES_NOT_EXIST`.
3. The iframe the step should run in isn't there: `FRAME_DOES_NOT_EXIST`.
4. The step's element wasn't found: `ELEMENT_DOES_NOT_EXIST`.
5. A waiting condition wasn't met: `FAILED_WAITING_CONDITIONS`.
6. A Scroll step didn't reach its position: `SCROLL_FAILED`.
7. Otherwise: `<STEP_TYPE>_FAILED`, for example `CLICK_FAILED`.

So the code tells you how far the step got. For example, `FAILED_WAITING_CONDITIONS` means the element was found, and `CLICK_FAILED` means the element was found and all waiting conditions passed.

## Errors and run statuses

| Status                                                    | When                                                                                                                                                                                                                                                     |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Failed**                                                | A step failed with any of the step error codes on this page.                                                                                                                                                                                             |
| **Step failed but the issue was ignored** (yellow circle) | A step failed, but it has **Continue on failure** enabled, so the test went on.                                                                                                                                                                          |
| **Passed with issues**                                    | The step passed, but some waiting conditions weren't fully met.                                                                                                                                                                                          |
| **Stopped**                                               | The run was stopped by a user, or the window or tab was closed or minimized (`WINDOW_CLOSED`, `TAB_CLOSED`, `WINDOW_MINIMIZED`).                                                                                                                         |
| **Error**                                                 | The run couldn't be completed: BugBug stopped receiving updates from the browser (`EXTENSION_DOES_NOT_RESPONSE_ERROR`), a cloud run waited in the queue for too long (`TEST_RUN_QUEUE_TIME_EXCEEDED`), or an internal error occurred (`INTERNAL_ERROR`). |

A site that is down or doesn't load gives `PAGE_LOADING_ERROR` and the **failed** status. See also [Statuses](https://docs.bugbug.io/running-tests/statuses.md).

## Generic step failures

Codes in the form `<STEP_TYPE>_FAILED` are built from the step type: `CLICK_FAILED`, `DBL_CLICK_FAILED`, `TYPE_FAILED`, `CHANGE_FAILED`, `HOVER_FAILED`, `UPLOAD_FILE_FAILED`, `ANSWER_PROMPT_FAILED`, `GOTO_FAILED` and so on. Three of them have a meaning of their own: `ASSERT_FAILED`, `SCROLL_FAILED` and `SELECT_FAILED` (see below).

**What it means:** the element was found and all waiting conditions passed, but the action itself didn't complete before the step's timeout, and no more specific error was reported.

**What to do:**

* Look at the step's screenshot and the [DOM snapshot](https://docs.bugbug.io/debugging-tests/dom-snapshot.md) from the failed run. Check that the selector points to the element that should get the action, not to a wrapper or a different element with the same text.
* Check the [console logs](https://docs.bugbug.io/debugging-tests/console-logs.md) and [network logs](https://docs.bugbug.io/debugging-tests/network-logs.md) for errors around that step.
* Check whether the page shows a browser dialog (alert, confirm, "Leave site?"). It blocks every action until an **Answer prompt** step handles it.
* Make sure the step type matches what the page expects, for example a double click instead of a click.
* Increase the step's [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md) if the action needs more time.
* If it happens only in the cloud, see [Cloud tests sometimes failing](https://docs.bugbug.io/troubleshooting/cloud-tests-sometimes-failing.md).

## Element and selector errors

| Code                                   | What it means                                                                                                                                                                                          | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ELEMENT_DOES_NOT_EXIST`               | No element matched the step's selector before the timeout.                                                                                                                                             | Check the screenshot: is the page where you expect it? Make sure the selector has no dynamic parts such as generated IDs. See [Selectors](https://docs.bugbug.io/preventing-failed-tests/selectors.md) and [Common selector issues](https://docs.bugbug.io/troubleshooting/common-selectors-issues.md). If the element is inside an iframe, check the Switch context step before it. If it loads only after scrolling, add a [Scroll step](https://docs.bugbug.io/preventing-failed-tests/smart-scroll.md). |
| `ELEMENT_REMOVED`                      | The element was found, but it was removed from the page while the step ran, and BugBug couldn't find it again.                                                                                         | The page re-rendered the element, for example after data loaded. Add a waiting condition or an assertion that waits for the page to settle before the step.                                                                                                                                                                                                                                                                                                                                                 |
| `SELECTOR_REQUIRED`                    | The step needs a selector, but it's empty.                                                                                                                                                             | Add a selector or re-record the step.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `INVALID_ELEMENT_SELECTOR`             | The selector isn't valid CSS or XPath.                                                                                                                                                                 | Fix the syntax. Test the selector in the browser's DevTools.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `INTERACTION_POSITION_OUT_OF_VIEWPORT` | The point BugBug should click is outside the browser window.                                                                                                                                           | Check that the selector doesn't point to a large container, and check the step's interaction position.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `EVENT_DISPATCHED_ON_INVALID_ELEMENT`  | BugBug tried to interact with the element, but another element received the event, for example a modal, cookie banner or sticky header on top of it. The message names the element that got the event. | Close or wait for the covering element in an earlier step. Check the screenshot to see what's on top. If the element is inside a web component and the reported element is part of it, change the selector to point to the inner element.                                                                                                                                                                                                                                                                   |
| `EVENT_DISPATCH_FAILED`                | The event was sent to the element, but it didn't complete as expected.                                                                                                                                 | Check that the element is enabled and that the step type matches what the page expects (for example double click).                                                                                                                                                                                                                                                                                                                                                                                          |
| `INVALID_MOUSE_INPUT_PARAMS`           | The mouse action has invalid parameters.                                                                                                                                                               | Re-record the step.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

## Waiting and timing errors

| Code                           | What it means                                                                                                                                                                   | What to do                                                                                                                                                                                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FAILED_WAITING_CONDITIONS`    | The element was found, but at least one of the step's [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md) wasn't met before the timeout. | Open the step's details in the failed run to see which condition failed. When **Element is not covered** fails, the run also shows what covers the element. Fix the cause on the page, or turn that condition off for this step if it doesn't apply. |
| `TIMEOUT`                      | The step didn't finish within its timeout.                                                                                                                                      | Increase the step's [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md), or check why the page is slow.                                                                                                                             |
| `SINGLE_TEST_TIME_EXCEEDED`    | A cloud run took longer than the maximum test duration of your plan. Local runs have no such limit.                                                                             | Shorten the test or split it into several tests. Look for long delays and waits.                                                                                                                                                                     |
| `TEST_RUN_QUEUE_TIME_EXCEEDED` | A cloud run waited in the queue for too long and was given the **error** status.                                                                                                | Run it again. If it repeats, contact support.                                                                                                                                                                                                        |

## Page, navigation and frame errors

| Code                           | What it means                                                                                                                                                                                                   | What to do                                                                                                                                                                                                 |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_GOTO_STEP`            | The test doesn't start with a **Go to URL** step.                                                                                                                                                               | Add a Go to URL step at the beginning. A test can also start with an Open inbox step.                                                                                                                      |
| `INVALID_URL`                  | The URL isn't valid.                                                                                                                                                                                            | Check that it starts with `http://` or `https://` and that any variable in it has a value.                                                                                                                 |
| `PAGE_LOADING_ERROR`           | The browser couldn't load the page. The message has Chrome's error, such as `ERR_NAME_NOT_RESOLVED`, `ERR_CONNECTION_REFUSED`, `ERR_CONNECTION_TIMED_OUT`, `ERR_CERT_DATE_INVALID` or `ERR_SSL_PROTOCOL_ERROR`. | Open the URL in your browser. In cloud runs, make sure the site is reachable from the internet or from the [cloud runner IP address](https://docs.bugbug.io/troubleshooting/ips-list-of-cloud-runners.md). |
| `HISTORY_ENTRY_DOES_NOT_EXIST` | A Go back or Go forward step had no page to go to.                                                                                                                                                              | Check that the earlier steps actually opened the page you want to go back to.                                                                                                                              |
| `FRAME_DOES_NOT_EXIST`         | The step should run in an iframe or a page that is no longer there.                                                                                                                                             | Check the **Switch context** step before it and its selector. If the iframe is reloaded or replaced, switch to it again. See [Tabs & iframes](https://docs.bugbug.io/editing-tests/tabs-and-iframes.md).   |
| `FRAME_LOADS_TOO_LONG`         | BugBug waited for the iframe to load, but it took too long.                                                                                                                                                     | Check the iframe in the console and network logs (blocked by CORS or CSP, or a server error). Increase the timeout if it's just slow.                                                                      |
| `FRAME_IS_NOT_INITIALIZED`     | The iframe exists, but BugBug couldn't start working in it.                                                                                                                                                     | Check the console logs for security errors. Run the test again.                                                                                                                                            |
| `WINDOW_OR_TAB_DOES_NOT_EXIST` | The tab the step should run in doesn't exist.                                                                                                                                                                   | Check the **Switch context** step and its tab number (the first tab is 0). Check that an earlier step really opens the tab.                                                                                |

## Form errors

| Code                                                                  | What it means                                                                                                                         | What to do                                                                                                                                  |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNCHANGABLE_ELEMENT`                                                 | The step needs a form field (input, textarea, select, checkbox or radio), but the selector points to another element.                 | Point the selector to the form field itself.                                                                                                |
| `TYPED_TEXT_DIFFERENT_THAN_EXPECTED`                                  | The text was typed, but the field ended up with a different value.                                                                    | Check for input masks, autocomplete or scripts that change the value. Use a **Change** step instead of **Type**.                            |
| `INVALID_FIELD_VALUE`                                                 | BugBug couldn't confirm that the field's value was changed.                                                                           | Same as above.                                                                                                                              |
| `SELECT_FAILED`                                                       | The option wasn't selected.                                                                                                           | Check that the option exists and that no script changes the selection back.                                                                 |
| `MISSING_OPTION_VALUE`, `MISSING_OPTION_TEXT`, `MISSING_OPTION_INDEX` | No option has this value, text or index. Indexes start at 0.                                                                          | Check the options in the current version of the page.                                                                                       |
| `INVALID_OPTION_INDEX`                                                | The option index isn't a number.                                                                                                      | Use a number, or check the variable that provides it.                                                                                       |
| `MULTIPLE_OPTIONS_WITH_VALUE`                                         | Several options have the same value, so BugBug can't tell which one to select.                                                        | Select by text or index instead.                                                                                                            |
| `FILE_DOES_NOT_EXIST`                                                 | The file for an **Upload file** step isn't available.                                                                                 | Upload the file to the step again.                                                                                                          |
| `FILE_UPLOAD_ERROR`                                                   | The file couldn't be uploaded to the field.                                                                                           | Check that the selector points to a file input.                                                                                             |
| `MEDIA_SOURCE_FILE_UNAVAILABLE`                                       | The file of a **Media source** step is missing, empty, can't be downloaded, or isn't a valid audio file (WAV, MP3, OGG, M4A or FLAC). | Choose the file again in the step, and check that it still exists in Files and has a supported format.                                      |
| `MEDIA_SOURCE_PERMISSIONS_NOT_ACCEPTED`                               | A **Media source** step ran while **Media permissions** is **Do not fake** or **Always decline**.                                     | Set **Media permissions** to **Always accept with default source** or **Always accept with custom source** in the project or test settings. |
| `GEOLOCATION_PERMISSION_DISABLED`                                     | A **Geolocation** step ran while **Location permission** is **Do not fake**.                                                          | Set **Location permission** to one of the **Always accept** options or **Always decline** in the project or test settings.                  |

## Variables and JavaScript

| Code                              | What it means                                                                                                                     | What to do                                                                                                                                        |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VARIABLE_DOES_NOT_EXIST`         | The step uses a variable that doesn't exist at that point of the test. The message has the variable name.                         | Check the name (it's case-sensitive). A [local variable](https://docs.bugbug.io/editing-tests/local-variables.md) must be set by an earlier step. |
| `VARIABLE_NESTING_LIMIT_EXCEEDED` | A variable's value refers to other variables more than 3 levels deep, or a variable refers to itself.                             | Reduce the nesting, and make sure no variable refers back to itself.                                                                              |
| `VALUE_COMPUTING_ERROR`           | BugBug couldn't compute a value, for example a variable that runs JavaScript.                                                     | Check the variable's definition and its JavaScript.                                                                                               |
| `CODE_EXECUTION_ERROR`            | [Custom JavaScript](https://docs.bugbug.io/editing-tests/custom-javascript-actions.md) threw an error. The message has the error. | Test the code in the browser console on the same page.                                                                                            |
| `INVALID_EXECUTION_RESULT`        | Custom JavaScript in an assertion didn't return `true` or `false`.                                                                | Return a boolean, for example `return Boolean(value)`.                                                                                            |
| `INVALID_DATA_FORMAT`             | A value has the wrong format for this step.                                                                                       | Correct the value in the step, or re-record it.                                                                                                   |

## Assertions, scroll, prompts, visual regression and accessibility

| Code                                                                | What it means                                                                                                                  | What to do                                                                                                                                                       |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ASSERT_FAILED`                                                     | The assertion wasn't true before the timeout.                                                                                  | Compare the expected value with the screenshot. The page may need more time or the expected value is out of date.                                                |
| `SCROLL_FAILED`                                                     | The Scroll step didn't reach the requested position.                                                                           | Check that the page or container can scroll that far.                                                                                                            |
| `NEXT_STEP_ELEMENT_REQUIRED`                                        | A Scroll step set to scroll until the next step's element is visible couldn't find that element.                               | Fix the next step's selector.                                                                                                                                    |
| `NEXT_ACTIVE_STEP_WITH_ELEMENT_REQUIRED`                            | The same Scroll setting, but the next active step has no element (for example Go to URL or Set variable).                      | Move the Scroll step right before a step that has an element.                                                                                                    |
| `PROMPT_DOES_NOT_EXIST`                                             | An **Answer prompt** step ran, but no browser dialog was open.                                                                 | Check that the earlier step opens the dialog. Custom HTML modals aren't browser dialogs: click them like any other element.                                      |
| `UNHANDLED_PROMPT`                                                  | A browser dialog (alert, confirm, prompt or "Leave site?") is open and blocks the step.                                        | Add an **Answer prompt** step right after the step that opens the dialog.                                                                                        |
| `ELEMENT_VISUAL_REGRESSION_FAILED`, `PAGE_VISUAL_REGRESSION_FAILED` | The screenshot differs from the reference more than allowed.                                                                   | [Review the difference](https://docs.bugbug.io/visual-regression/review-and-fix.md) and accept the new screenshot or fix the page.                               |
| `REFERENCE_SCREENSHOT_NOT_FOUND`                                    | The visual regression step has no reference screenshot.                                                                        | Set the reference screenshot for the step.                                                                                                                       |
| `SCREENSHOT_CAPTURE_ERROR`                                          | The screenshot couldn't be taken, for example because the element has no size.                                                 | Check that the element is visible. Run the test again.                                                                                                           |
| `SCREENSHOT_COMPARISON_ERROR`                                       | The screenshots couldn't be compared.                                                                                          | Run the test again. If it repeats, contact support.                                                                                                              |
| `ACCESSIBILITY_CHECK_FAILED`                                        | The page has accessibility issues at or above the impact set in the step's "Detect issues" threshold.                          | Open "View issues" in the step details and fix the reported elements, for example with "Fix with your AI agent". Or raise the step's threshold or skip the rule. |
| `ACCESSIBILITY_SCAN_ERROR`                                          | The accessibility scan couldn't be completed, for example because the page can't be scanned (such as a browser-internal page). | Run the test again. If it repeats, contact support.                                                                                                              |

## Browser and extension errors

These mostly happen in [local runs](https://docs.bugbug.io/running-tests/test-in-your-browser.md), where the test runs in your own browser.

| Code                                                     | What it means                                                                                                                                  | What to do                                                                                                    |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `TAB_CLOSED`, `WINDOW_CLOSED`                            | The tab or window running the test was closed. The run is **stopped**.                                                                         | Don't close the test window during a run. Check that the test doesn't close its last tab.                     |
| `WINDOW_MINIMIZED`                                       | The test window was minimized. The run is **stopped**.                                                                                         | Keep the window open while the test runs.                                                                     |
| `UNEXPECTED_WINDOW_STATE_CHANGE`                         | The test window was minimized or lost its state because of another action, for example switching macOS Spaces.                                 | Leave the window alone while the test runs.                                                                   |
| `DEBUGGER_DETACHED`                                      | BugBug lost its connection to the browser tab, usually because **Cancel** was clicked on Chrome's "BugBug started debugging this browser" bar. | Don't click Cancel on that bar during a run. Close DevTools or other debugging extensions on the tab.         |
| `BLOCKED_BY_BROWSER_POLICY`                              | The browser doesn't allow extensions on this page, for example because of a company policy.                                                    | Ask your IT administrator. In Opera, enable **Allow access to search page results** for the BugBug extension. |
| `UNSUPPORTED_BROWSER`                                    | The browser isn't supported.                                                                                                                   | Update Chrome to the latest version.                                                                          |
| `EXTENSION_DISCONNECTED`, `EXTENSION_DISCONNECTED_ERROR` | The BugBug extension lost its connection to BugBug.                                                                                            | Check your internet connection and make sure the extension wasn't reloaded or updated during the run.         |
| `EXTENSION_DOES_NOT_RESPONSE_ERROR`                      | BugBug stopped receiving updates from the browser. The run gets the **error** status.                                                          | Run the test again.                                                                                           |
| `INVALID_CUSTOM_HEADERS`                                 | The HTTP request headers in [project settings](https://docs.bugbug.io/preventing-failed-tests/project-settings.md) are invalid.                | Header names can't contain spaces or colons.                                                                  |
| `AUTHENTICATION_ERROR`                                   | Signing in to a password-protected page failed.                                                                                                | Check the credentials.                                                                                        |

## Reusable browser session errors

### BROWSER\_STATE\_CAPTURE\_FAILED

The steps of the "Before all" test selected to [reuse its browser session](https://docs.bugbug.io/organizing-tests/suites/reusable-browser-session.md) finished successfully, but BugBug could not save its cookies and localStorage. The test is marked "failed" and the suite stops, like after any other failed "Before all" test.

**When occurs?**:

* The browser did not send the saved session within 60 seconds after the last step
* The saved session is larger than 5 MB

**What to do?**:

* Run the suite again
* If your application stores a lot of data in localStorage, check whether it really needs to keep it for the session

### BROWSER\_STATE\_RESTORE\_FAILED

A main suite test could not start with the browser session saved by the "Before all" test.

**When occurs?**:

* Restoring the cookies and localStorage took longer than 60 seconds
* The browser could not download the saved session from BugBug

Rejected cookies or sites whose localStorage can't be written don't cause this error, even if all items are rejected. They are reported under "Show session details", and the test continues. A cookie that expired before restore also doesn't cause this error; see [Cookies and restore results](https://docs.bugbug.io/organizing-tests/suites/reusable-browser-session.md#cookies-and-restore-results).

**What to do?**:

* Run the suite again
* If it keeps failing, turn off "Reuse browser session across main tests" in the "Before all" settings and let the tests log in on their own

## Internal errors

`RUNTIME_ERROR`, `INTERNAL_ERROR`, `INITIALIZATION_ERROR`, `STEP_RUN_INITIALIZATION_ERROR`, `UNRECOGNIZED_STEP_TYPE`, `REQUEST_ERROR`, `WEBSOCKET_ERROR`, `WEBSOCKET_SETUP_ERROR` and `LOGS_UPLOAD_TIMEOUT` mean something went wrong in BugBug, the browser or the connection between them, not in your test. Run the test again. If it repeats, contact support and include the link to the run.

A `RUNTIME_ERROR` whose message starts with "An error occurred during browser API call" passes on an error from Chrome. For example, "Cannot navigate to a file URL without local file access" means the page tried to open a `file://` address.

## FAQ

<details>

<summary>What does CLICK_FAILED (or DBL_CLICK_FAILED, TYPE_FAILED) mean when all waiting conditions passed?</summary>

The element was found and the waiting conditions passed, but the click didn't complete before the step's timeout. Check the screenshot and DOM snapshot to make sure the selector points to the right element, check the logs for errors, and check for an open browser dialog. See [Generic step failures](#generic-step-failures).

</details>

<details>

<summary>How do I find out which waiting condition failed?</summary>

Open the failed step in the run details. The waiting conditions are listed with their result. For **Element is not covered**, the run also shows the element that was on top.

</details>

<details>

<summary>Is a site that is down a failed test or an error?</summary>

Failed. The step fails with `PAGE_LOADING_ERROR`. The **error** status is for runs that couldn't be completed, for example when BugBug stopped receiving updates from the browser.

</details>

<details>

<summary>Why do I get ELEMENT_DOES_NOT_EXIST when the element is visible in the screenshot?</summary>

The selector doesn't match it, or the step runs in a different context. Check whether the element is inside an iframe (it needs a Switch context step first), whether the selector contains text or IDs that changed, and whether a browser dialog blocks the page.

</details>

<details>

<summary>Why does the error say FRAME_DOES_NOT_EXIST on a step that doesn't use an iframe?</summary>

The step runs in the top frame of the page, and BugBug couldn't reach that frame before the timeout. Check the screenshot of the step and of the previous one: is a page loaded at all, and is it the page you expect? Check that the Go to URL step before it opens a real `http(s)` address.

</details>

<details>

<summary>What happens when a selector matches more than one element?</summary>

BugBug uses the first matching element, in page order. There is no error or warning. If the step acts on the wrong element, make the selector more specific. See [Selectors](https://docs.bugbug.io/preventing-failed-tests/selectors.md).

</details>

<details>

<summary>How long can a single test run?</summary>

Steps have their own [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md). A whole cloud run is limited by your plan; when it's exceeded the run fails with `SINGLE_TEST_TIME_EXCEEDED`. Local runs have no such limit.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/debugging-tests/error-codes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
