> 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/preventing-failed-tests/timeout.md).

# Timeout

How long BugBug tries a step before failing it: default timeouts for local and cloud runs, how the timeout works with waiting conditions and retries, how to change it, and the maximum cloud test durat

The timeout is the maximum time, in seconds, that BugBug spends on one step. During this time BugBug waits for the step's [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md), runs the step, and retries it if it doesn't pass, for example an assertion that is checked again every 1.5 seconds. If the step still doesn't pass when the timeout ends, the test fails.

The default timeout is **30 seconds in local runs** and **60 seconds in cloud runs**. The maximum is **300 seconds**.

## How the timeout is used

* **It starts after the delay.** If the step has a [delay](https://docs.bugbug.io/preventing-failed-tests/delay-sleep.md), the timeout starts counting when the delay ends.
* **Part of it is for waiting conditions.** After 70% of the timeout (for timeouts up to 10 seconds) or 50% (for longer timeouts), BugBug skips optional waiting conditions that still aren't met and runs the step. With the defaults, that's after 15 seconds locally and 30 seconds in the cloud. See [How a step waits](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md#how-a-step-waits).
* **A step that passes doesn't wait for the timeout.** The timeout is only a limit; BugBug continues as soon as the step succeeds.

## Configure global timeout

Set the timeout for local and cloud runs separately in [Project settings](https://docs.bugbug.io/preventing-failed-tests/project-settings.md) → **General**.

* Increase it if your page is slow or tests fail in the cloud. See [Cloud tests sometimes failing](https://docs.bugbug.io/troubleshooting/cloud-tests-sometimes-failing.md).
* Decrease it if you don't want to wait that long for a failed test result.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Fy61oTf1lc2SGoV7n09ki%2FScreen%20Shot%202022-11-24%20at%2013.20.21.png?alt=media&amp;token=d51b1216-f10d-4b8d-8589-2fe568196d7b" alt="Timeout settings for local and cloud runs in project settings"><figcaption></figcaption></figure>

## Change timeout for individual steps

You can set a different timeout, up to 300 seconds, for one step in the step's settings. It replaces the project timeout for this step, in local and cloud runs. Leave it empty to use the project timeout.

![Timeout field in the step settings](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FdkUGZF5M3AI7PAIScCTi%2FScreenshot%202022-04-11%20at%2019.22.39.png?alt=media\&token=969ce483-dc8e-4263-ad9d-c5aff531a9ea)

In [YAML](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md) the field is `execution.run_timeout`, and in the API and MCP `runTimeout`, both in seconds:

```yaml
- action: click
  action_details:
    selector: "css=button.export"
  execution:
    run_timeout: 90
```

{% hint style="info" %}
Raise the timeout for the slow step only, not for the whole project. A longer project timeout makes every failing step take longer to fail.
{% endhint %}

## Maximum test duration in the cloud

Besides the step timeout, a single test running in the cloud has a maximum duration, counted from the start of the test run:

| Plan               | Maximum duration of a single cloud test |
| ------------------ | --------------------------------------- |
| Core               | 10 minutes                              |
| Pro                | 15 minutes                              |
| Business and trial | 30 minutes                              |

When a cloud test runs longer, it fails with `SINGLE_TEST_TIME_EXCEEDED`. Local runs don't have this limit. If your tests get close to the limit, split them into shorter tests and run them in a [suite](https://docs.bugbug.io/organizing-tests/suites.md).

## Related errors

| Error code                  | Meaning                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `FAILED_WAITING_CONDITIONS` | A required waiting condition wasn't met before the timeout.                            |
| `ELEMENT_DOES_NOT_EXIST`    | No element matched the selector before the timeout.                                    |
| `ASSERT_FAILED`             | The assertion didn't pass before the timeout.                                          |
| `TIMEOUT`                   | The step didn't finish before the timeout, for example a slow page or long JavaScript. |
| `SINGLE_TEST_TIME_EXCEEDED` | A cloud test ran longer than the maximum test duration of your plan.                   |

See all [error codes](https://docs.bugbug.io/debugging-tests/error-codes.md).


---

# 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/preventing-failed-tests/timeout.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.
