> 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/troubleshooting/cloud-tests-sometimes-failing.md).

# Cloud tests sometimes failing

Why a BugBug test can pass locally but sometimes fail in the cloud, and how to fix it: timeouts, waiting conditions, the Cloud Proxy IP address, sessions, page loading errors, auto-retry and how to fi

A test that passes in your browser can fail in the cloud, every time or only sometimes. The cause is usually one of the differences between a [local and a cloud run](https://docs.bugbug.io/running-tests/in-cloud-on-server.md#how-a-cloud-run-differs-from-a-local-run): cloud machines can be slower, the cloud browser is always fresh, and it reaches your site from the Cloud Proxy's IP address, not from yours.

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

* Find the cause first: open the failed run in [runs history](https://docs.bugbug.io/debugging-tests/runs-history.md) and check the failed step's error code and screenshot.
* Slow pages: raise the timeout of the slow step, or the **Default cloud run timeout** in project settings.
* Site blocks the cloud: allow the [Cloud Proxy's IP address](https://docs.bugbug.io/preventing-failed-tests/project-settings.md#cloud-runner-ip-addresses).
* Random, rare failures: turn on auto-retry in the suite.
  {% endhint %}

## Find the cause

Open the failed cloud run in [runs history](https://docs.bugbug.io/debugging-tests/runs-history.md) and click the failed step:

* **Error code.** It says what went wrong, with tips. See [Error codes](https://docs.bugbug.io/debugging-tests/error-codes.md).
* **Screenshots.** They show the page right before BugBug tried the step, for example a loader, a cookie banner or an error page. See [Screenshots](https://docs.bugbug.io/debugging-tests/screenshots.md).
* **Waiting conditions.** For `FAILED_WAITING_CONDITIONS`, the step details show which condition wasn't met.
* **DOM snapshot and logs.** The [DOM snapshot](https://docs.bugbug.io/debugging-tests/dom-snapshot.md) shows the page's HTML at the failure. Turn on [console logs](https://docs.bugbug.io/debugging-tests/console-logs.md) and [network logs](https://docs.bugbug.io/debugging-tests/network-logs.md) in project settings to see errors and failed requests.

## Common causes and fixes

| What you see                                                                       | Likely cause                                                      | Fix                                                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TIMEOUT`, `ELEMENT_DOES_NOT_EXIST` or `ASSERT_FAILED` on a page that loads slowly | The cloud machine is slower than your computer                    | Raise the [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md) of the slow step, or **Default cloud run timeout** in **Project settings → General** (default: 60 seconds).                                                                                                                    |
| `FAILED_WAITING_CONDITIONS` with **Page network requests are finished**            | The page keeps connections open, for example analytics or polling | Raise **Max. pending requests** or turn the condition off for that step. See [Waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md).                                                                                                                                      |
| `FAILED_WAITING_CONDITIONS` with **Element is not covered**                        | A cookie banner, popup or loader covers the element               | Close the banner in the test, for example with an [If condition](https://docs.bugbug.io/editing-tests/conditional-logic-if-else.md) step.                                                                                                                                                                     |
| `PAGE_LOADING_ERROR`, or an error page in the screenshot                           | The site doesn't let the cloud in, or its certificate isn't valid | Allow the [Cloud Proxy's IP address](https://docs.bugbug.io/preventing-failed-tests/project-settings.md#cloud-runner-ip-addresses) in your firewall or VPN, use a valid HTTPS certificate, and raise the cloud timeout. See [VPN or a Firewall](https://docs.bugbug.io/troubleshooting/vpn-or-a-firewall.md). |
| The test isn't logged in, or data from an earlier run is missing                   | Every cloud run starts with a fresh browser                       | Log in within each test, for example with a [component](https://docs.bugbug.io/editing-tests/components.md), and don't rely on another test. See [Independent tests](https://docs.bugbug.io/creating-tests/independent-tests.md).                                                                             |
| A CAPTCHA or a "verify you're human" page                                          | Bot protection on your site                                       | Turn it off for tests or allow the Cloud Proxy's IP address. See [CAPTCHA in automation testing](https://docs.bugbug.io/troubleshooting/captcha-in-automation-testing.md).                                                                                                                                    |
| Different content, language or prices                                              | Your site adapts to the visitor's location                        | Choose another **Cloud Proxy** location, or set **Browser language** in [project settings](https://docs.bugbug.io/preventing-failed-tests/project-settings.md).                                                                                                                                               |

## Change the cloud timeout

1. Go to **Project settings → General**.
2. Change **Default cloud run timeout** to a higher value, in seconds.
3. Save the settings.

![Default cloud run timeout in project settings](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F8o1CvbgZhB7OzJUGoVSF%2Fcloud%20run%20timeout.png?alt=media\&token=f5736c8c-4d53-45b2-a2d6-7c64696de9ee)

Raise the timeout of the slow step first, if you know which one it is. A higher project timeout makes every failing step take longer to fail. The maximum for a step is 300 seconds.

## Avoid false alarms with auto-retry

If a test fails only now and then and passes when you run it again, turn on **auto-retry** in the [suite](https://docs.bugbug.io/organizing-tests/suites.md#auto-retry-failed-cloud-tests-to-prevent-flaky-tests-notifications). A failed test is run again, and the suite passes if a later attempt passes. The failed attempts stay in runs history, marked as auto-retried, so you can still find and fix the cause.

## FAQ

<details>

<summary>Why does my test pass locally but fail in the cloud?</summary>

Most often the page is slower in the cloud, your site blocks the Cloud Proxy's IP address, or the test relies on something only your browser has, such as a session. Check the failed step's error code and screenshot, then use the fixes in [Common causes and fixes](#common-causes-and-fixes).

</details>

<details>

<summary>Where do I change the cloud timeout?</summary>

In **Project settings → General → Default cloud run timeout**. Default: 60 seconds. A single step can have its own timeout, up to 300 seconds.

</details>

<details>

<summary>Which IP address does my firewall need to allow?</summary>

The IP address of the Cloud Proxy selected in project settings. See [Cloud runner IP addresses](https://docs.bugbug.io/preventing-failed-tests/project-settings.md#cloud-runner-ip-addresses).

</details>

<details>

<summary>Should I add delays to make cloud tests stable?</summary>

Usually not. BugBug already waits for the page and the element with [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md), up to the step's timeout. A fixed [delay](https://docs.bugbug.io/preventing-failed-tests/delay-sleep.md) makes every run slower. Raise the timeout or fix the waiting condition that fails instead.

</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/troubleshooting/cloud-tests-sometimes-failing.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.
