> For the complete documentation index, see [llms.txt](https://manual.bubble.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.bubble.io/help-guides/logic/workflows.md).

# Workflows

Workflows are how a Bubble app responds to events. Learn how events and actions work together, how to organize and find workflows, and how to handle errors and timeouts.

{% embed url="<https://youtu.be/jx01hwKhXVQ>" %}

Workflows are the engine of your app. They're how you tell Bubble to respond to what the user does, such as clicking a button, with a set of actions. Those actions can do anything from hiding, showing, or animating elements[^1] to making changes in the database[^2] and making external [API calls](#user-content-fn-3)[^3].

A *workflow* is the combination of an *event* that triggers one or more *actions*.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FixsfXqyGYp0EYeqkGX3u%2Fworkflow-schema.jpeg?alt=media&amp;token=31eb1a55-017c-44c0-bcca-c09cf4608c44" alt="A diagram of a workflow: an event with an arrow pointing to actions."><figcaption><p>An event triggers one or more actions, and together they make up a workflow.</p></figcaption></figure>

You build workflows in the **Workflow** tab, where each page has its own set of workflows. Workflows that run on the server have their own tab, **Backend workflows**.

***

## Events

An event is anything that tells a workflow to run, such as:

* A button being clicked
* An input's value being changed
* A condition being true
* A user logging in or out
* Changes in the database

[Frontend events](https://manual.bubble.io/help-guides/logic/workflows/events/frontend-events.md) happen on a page, or on a view[^4] if you're using [Bubble for native mobile apps](https://manual.bubble.io/help-guides/getting-started/building-for.../native-ios-and-android.md). [Backend events](https://manual.bubble.io/help-guides/logic/workflows/events/backend-events.md) happen on Bubble's server, so they don't need anyone to have your app open.

**Article series:** [Events](https://manual.bubble.io/help-guides/logic/workflows/events.md)

***

## Actions

Actions are the operations that take place when an event triggers a workflow. You can place as many actions as you need inside one workflow, and they're how your app responds to a user or to a change in conditions. Here are some of the things they can do:

<table><thead><tr><th width="229.1796875">Action type</th><th>What it can do</th></tr></thead><tbody><tr><td>Account</td><td>Create user accounts and log users in and out</td></tr><tr><td>Data (things)</td><td>Create, update, and delete things in your database</td></tr><tr><td>Elements</td><td>Hide, show, and animate elements, and load data into them</td></tr><tr><td>Navigation</td><td>Send the user to a different page, or to a different view in a native mobile app</td></tr><tr><td>Email and notifications</td><td>Send emails, and push notifications in a native mobile app</td></tr><tr><td>Native mobile</td><td>Use features specific to apps for iOS and Android, such as location services</td></tr><tr><td>Plugins</td><td>Use <a href="https://manual.bubble.io/help-guides/integrations/api/plugins-that-connect-to-apis.md">plugins</a>, such as making a payment</td></tr></tbody></table>

{% hint style="info" %}
Actions start in the order you place them, but a step doesn't always wait for the previous one to finish, because some actions run on the user's device and others on Bubble's server.

**Article section:** [The order in which actions are triggered](https://manual.bubble.io/help-guides/logic/workflows/actions.md#the-order-in-which-actions-are-triggered)
{% endhint %}

**Article:** [Actions](https://manual.bubble.io/help-guides/logic/workflows/actions.md)

***

## The workflow canvas

{% embed url="<https://youtu.be/nbMdh3TExsA>" %}

The workflow canvas helps you stay focused by letting you work on one workflow at a time. Workflows are arranged vertically, with the event at the top and a list of actions in sequence beneath it.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FcAfcvE1sODXPkcfTC36L%2Fworkflow-canvas-bubble.png?alt=media&amp;token=5280a8c2-d7dc-4ff8-9ed1-b69a3bb45da1" alt="The workflow canvas showing the Button Sign up flow workflow, with a Button Sign up is clicked event above a Sign the user up action that has an Only when condition."><figcaption><p>A workflow reads from top to bottom, starting with the event.</p></figcaption></figure>

Each action category has its own icon on the left, which makes it easy to spot specific actions in your workflow. In the example above, the user icon shows that the action belongs to the *Account* category.

Next to the icon is the action label, which you can customize in the workflow property editor. Underneath it, you'll see any [condition](https://manual.bubble.io/help-guides/logic/conditions.md) placed on the action.

***

## Organizing workflows

{% embed url="<https://youtu.be/2H07G-MfQcM>" %}

You can organize your workflows in two ways: by adding colors and by creating folders. There are no fixed rules for how to use them, but it's worth thinking about how the two can work together, especially on pages with a lot of workflows.

{% hint style="info" %}
**Best practice:** Bubble automatically names workflows when you create them. Giving your workflows custom, descriptive names makes them easier to identify, organize, and search for later.
{% endhint %}

### Colors

Each workflow can have one of the following colors:

* Gray (default)
* Blue
* Red
* Green
* Orange
* Purple
* Cyan
* Brown

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FI11lXxn0mnMkVVVAJU0B%2Fworkflow-colors.png?alt=media&amp;token=71a7b645-fa45-485a-9b04-9c81a50245dd" alt="The workflow list with a workflow&#x27;s right-click menu open and the Change color option expanded to show the available colors."><figcaption><p>Right-click a workflow and select <em>Change color</em> to pick a color.</p></figcaption></figure>

### Folders

{% embed url="<https://youtu.be/Rza2JW2lmR0>" %}

You can also organize workflows into folders, available in the left-hand menu of the workflow canvas. Each folder can have a custom name. To add a new workflow to a folder, hover over the folder and click the *+* symbol that appears. You can also drag and drop workflows between folders.

By default, all workflows are placed in the *Uncategorized* folder. In the example below, we've created a custom folder and named it *Buttons*.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FqXobATUBgieSImaMGJ3X%2FCleanShot%202026-10-13%20at%2013.11.36.png?alt=media&amp;token=fc7a66bf-fe9c-4ef3-9713-aad056a4f8ae" alt="The workflow list in the Workflow tab, with a folder called Buttons highlighted, containing the Button Sign up flow workflow."><figcaption><p>Each folder name is followed by the number of workflows inside it.</p></figcaption></figure>

Folders are only there to keep the editor organized. They don't affect how workflows run, the order they run in, or what users see in your app.

***

## Searching for workflows

The search field lets you quickly find a workflow. You can search for events and actions by typing their name or description:

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FrdWt2DHOhyLooNFlLP9F%2FCleanShot%202026-10-13%20at%2013.13.21.png?alt=media&amp;token=672d6049-a591-4ac4-aa66-96143c47a5d6" alt="The workflow search open in the editor, listing matching events with the actions inside them."><figcaption><p>Search results list each event along with its actions.</p></figcaption></figure>

***

## Sharing workflows

Every workflow has its own URL, which you can copy from your browser's address bar while the workflow is open. This is helpful for keeping detailed notes[^5], by including the URL of a specific workflow in the note, or for sending a direct link to your collaborators[^6].

***

## Disabling workflows and actions

You can stop a workflow from running without deleting it. Right-click the workflow in the workflow list and select *Disable workflow*, and you can turn it back on from the same menu.

This is especially useful when you're debugging[^7], since you can test one piece of functionality without other workflows getting in the way. You can also use it while you change a workflow, by disabling a copy of the working version and keeping it for reference.

To skip a single step instead of a whole workflow, select the action and turn on *Disable Action* in the **Execution options** section of the workflow property editor. The workflow still runs, but it skips that action. The action keeps its properties, conditions, and position until you turn the toggle off.

{% hint style="info" %}
Backend workflows can't be disabled as a whole, but you can disable their individual actions.
{% endhint %}

***

## Changing how workflows are displayed

You can adjust how workflows appear in the editor. Most of these options are behind the *Filter/view* icon at the top of the workflow list.

### Grouping workflows

The *By Folder* option groups workflows by the folders you create, while *By Event Type* groups them by event, such as *Page is loaded* or *An element is clicked*. If you mainly look for workflows by what triggers them, *By Event Type* can be a quick way to find them without setting up folders.

### Show conditions

In the list or grid of workflows, you can choose to see the conditions on each workflow:

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2F2hr5lOCfeVIy1sAUypJo%2FCleanShot%202026-10-13%20at%2013.16.09.png?alt=media&amp;token=7458cd06-461e-4620-9c19-6cd52b8083d4" alt="The workflow list showing a workflow called Workflow 1, with its condition, Current User is logged in, underlined beneath its name."><figcaption><p>With <em>Show Conditions</em> on, each workflow's condition appears under its name.</p></figcaption></figure>

To turn this on, click the *Filter/view* icon and select *Show Conditions*.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FArlZsApTEfRle6BxJxmG%2FCleanShot%202026-10-13%20at%2013.16.48.png?alt=media&amp;token=19272fbb-a573-4df4-9309-29e6a57211c8" alt="The workflow list&#x27;s view options menu with Show Conditions highlighted."><figcaption><p>The <em>Filter/view</em> menu holds the options for grouping and displaying workflows.</p></figcaption></figure>

### Grid view

You can also see workflows arranged in a grid instead of a list. To turn this on, click the *Filter/view* icon and select *Grid View*.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FEe6z6UIMgOb6L5oRZL3V%2FCleanShot%202026-10-13%20at%2013.19.02.png?alt=media&amp;token=4d2a33b9-2fbc-4ad6-bef2-e8dc83bd3444" alt="The workflow list&#x27;s view options menu with Grid View selected and the options icon highlighted, showing the page&#x27;s workflows arranged in a grid, grouped by folder."><figcaption><p><em>Grid view</em> lets you view your workflows in a grid instead of a list.</p></figcaption></figure>

### Compact mode

Compact mode shows workflows in smaller rectangles, so more steps fit on the screen at once. Events and actions are left-aligned and use more of the screen's width.

To switch between compact and normal view, click the icons in the upper-right corner of the workflow canvas:

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FgJTq96GVhQTKCSbilsGi%2FCleanShot%202026-10-13%20at%2013.14.04.png?alt=media&amp;token=b0129b29-854d-4c5b-89c0-cfec200f68b6" alt="A workflow on the workflow canvas shown in compact mode, with the buttons for turning compact mode on and off highlighted in the upper-right corner."><figcaption><p>Use these icons to switch between compact and normal view.</p></figcaption></figure>

***

## Errors in workflows

Workflows can hit errors in different situations. For example:

* A user tries to log in using the wrong credentials
* A user tries to sign up using an email that already exists in the database
* A credit card payment fails because the card is declined

If a workflow runs into an error, it stops on the action where the error happened. Any previous actions aren't reverted.

{% hint style="info" %}
These are errors that happen while your app is running. They're different from the issues flagged by the [issue checker](https://manual.bubble.io/help-guides/getting-started/navigating-the-bubble-editor/tools/the-issue-tracker.md) in the editor.
{% endhint %}

### Handling errors

By default, Bubble shows most errors in the browser's standard message popup. To handle them yourself, on a specific element or more broadly on a page, you can use two events:

| Event                                        | What it catches                                                                                                                                                     | Learn more                                                                                                                                                                                                                                |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *An element has an error running a workflow* | Errors related to a specific element. For example, if a *Log in* button starts a workflow with the *Log the user in* action, the error is connected to that button. | [Example: catching errors](https://manual.bubble.io/help-guides/logic/workflows/events/frontend-events.md#example-catching-errors)                                                                                                        |
| *An unhandled error occurs*                  | Any error on the page, unless another error event catches it first.                                                                                                 | [An unhandled error occurs](https://manual.bubble.io/help-guides/logic/workflows/events/frontend-events.md#an-unhandled-error-occurs), [How to use the Unhandled Error Occurs event](https://www.youtube.com/watch?v=VC2_8yiTD44) (video) |

***

## Workflow timeouts

In rare cases, workflows can [time out](#user-content-fn-8)[^8]. Workflows that take more than 300 seconds (five minutes) time out, which generally means the server has been overwhelmed with tasks it can't complete in that window. Bubble may also halt processing to preserve system stability, or timeouts may happen because of technical issues like lost server connections.

Timeouts are more likely with [highly complex workflows](#user-content-fn-9)[^9] or those processing large volumes of data. For instance, operations like *Make changes to a list of things* are efficient for up to 1,000 records but may slow down or time out beyond that number. For lists approaching or exceeding 10,000 records, we recommend using backend operations, which are better suited for large data volumes.

If you plan to work with large amounts of data or demanding server processes, it can also help to learn about bulk operations and how to optimize your app for performance and workload[^10].

**Article:** [Bulk operations](https://manual.bubble.io/help-guides/maintaining-an-application/database-maintenance/bulk-operations.md)\
**Article series:** [Optimizing workload](https://manual.bubble.io/help-guides/workload/optimizing-workload.md)\
**Article section:** [Workflow timeout](https://manual.bubble.io/help-guides/maintaining-an-application/performance-and-scaling/hard-limits.md#workflow-timeout)

***

## Build workflows with Bubble AI

You can ask the [Bubble AI Agent](https://manual.bubble.io/help-guides/ai/bubble-ai-agent.md) to create and edit workflows for you. Describe what should happen in plain language, and depending on the approval mode you've picked, the Agent can show you a plan to approve or cancel before it changes anything. Then open the **Workflow** tab to see what it built and edit it yourself. You can also ask the Agent to explain what a workflow does or help you troubleshoot it.

The Agent works best with simpler prompts, and it declines very complex workflows. It supports a set list of [events and actions in frontend workflows](https://manual.bubble.io/help-guides/ai/bubble-ai-agent/edit-apps-with-ai.md#generate-and-modify-frontend-workflows). In [backend workflows](https://manual.bubble.io/help-guides/ai/bubble-ai-agent/edit-apps-with-ai.md#generate-and-modify-backend-workflows), it can't build custom events, payment actions, or analytics actions, it can't manage workflow folders, and it can't run or test a workflow for you. It can still explain how to set up things it can't build.

Here are a few prompts to try:

{% code overflow="wrap" %}

```
Create a workflow that runs when the user clicks the Save button. It should create a new Task using the value from the Task name input, then reset the inputs.
```

{% endcode %}

{% code overflow="wrap" %}

```
Create a workflow that sends the user to the login page when they're logged out.
```

{% endcode %}

{% code overflow="wrap" %}

```
Create a workflow that shows an alert when an unhandled error occurs.
```

{% endcode %}

```
Explain what this workflow does.
```

```
Are there any buttons missing workflows on this page?
```

**Article:** [Edit apps with AI](https://manual.bubble.io/help-guides/ai/bubble-ai-agent/edit-apps-with-ai.md)

***

## FAQ: Workflows

<details>

<summary>What is a workflow in Bubble?</summary>

A workflow is an event that triggers one or more actions. For example, a user clicking a button (the event) can create a new thing in the database (the action).

</details>

<details>

<summary>How many actions can a workflow have?</summary>

You can add as many actions as you need. Keep in mind that a workflow times out if it takes more than five minutes, and that each server-side action can add to your workload.

</details>

<details>

<summary>Do actions always run in the order I place them?</summary>

They start in that order, but a step doesn't always wait for the previous one to finish. When a workflow mixes actions that run on the user's device with actions that run on the server, they may not finish in the order they appear. To use data from an earlier step, the safest option is the `Result of step X` data source.

**Article section:** [The order in which actions are triggered](https://manual.bubble.io/help-guides/logic/workflows/actions.md#the-order-in-which-actions-are-triggered)

</details>

<details>

<summary>What happens when a workflow hits an error?</summary>

The workflow stops on the action where the error happened, and any previous actions aren't reverted. You can catch the error with the *An element has an error running a workflow* or *An unhandled error occurs* event. See [Handling errors](#handling-errors).

</details>

<details>

<summary>Do folders affect how my workflows run?</summary>

No. Folders are only there to organize the editor. They don't affect how workflows run, the order they run in, or what users see in your app.

</details>

<details>

<summary>Are workflows secure?</summary>

Backend workflows run on Bubble's server, away from the user. Frontend workflows run at least partly on the user's device, so don't rely on them alone. Use conditions the server can check, and protect data with [privacy rules](https://manual.bubble.io/help-guides/data/the-database/protecting-data-with-privacy-rules.md). The [security dashboard](https://manual.bubble.io/help-guides/security/security-dashboard.md) can also flag sensitive data exposed in workflows.

**Article:** [Client-side and server-side](https://manual.bubble.io/help-guides/security/client-side-and-server-side.md)

</details>

<details>

<summary>Do workflows use workload?</summary>

A workflow doesn't cost anything by itself. It's the server-side actions and expressions inside it that use workload. Actions that run only on the user's device don't add to it.

**Article:** [Workflows and actions](https://manual.bubble.io/help-guides/workload/optimizing-workload/optimization-checklist/workflows-and-actions.md)

</details>

<details>

<summary>Do workflows work in native mobile apps?</summary>

Yes. Workflows work the same way, with an event that triggers one or more actions. In a native mobile app, frontend events happen on a view instead of a page, and you also get mobile-specific actions, such as navigating between views and sending push notifications.

**Article:** [Native mobile vs. web development](https://manual.bubble.io/help-guides/getting-started/building-for.../native-ios-and-android/native-mobile-vs.-web-development.md)

</details>

[^1]: *Elements* are the objects that you place on the page as you design your app. There are many different types of elements, like texts, buttons, input fields, and calendars.\
    **Article series:** [Elements](https://manual.bubble.io/help-guides/design/elements.md)

[^2]: The database stores all your app's data, such as users, posts, and orders.\
    **Article:** [The database](https://manual.bubble.io/help-guides/data/the-database.md)

[^3]: An API call sends a request to an external app to get data back. For example, you could send a request to a weather service to get updated weather information. Outgoing API calls are made with the API Connector.\
    **Article:** [The API Connector](https://manual.bubble.io/help-guides/integrations/api/the-api-connector.md)

[^4]: A view is the top-level element in a native mobile app, serving the same role that a page does in a web app.\
    **Article:** [The view element (mobile)](https://manual.bubble.io/help-guides/design/elements/ios-and-android-app/the-view.md)

[^5]: Bubble lets you attach notes to different components in your app.\
    **Article:** [Notes](https://manual.bubble.io/help-guides/getting-started/navigating-the-bubble-editor/tools/notes.md)

[^6]: You can add collaborators to your app to work together as a team.\
    **Article:** [Collaborators](https://manual.bubble.io/help-guides/maintaining-an-application/collaboration.md)

[^7]: The debugger lets you check your workflows and element properties in real time when you preview your app.\
    **Article:** [The debugger](https://manual.bubble.io/help-guides/getting-started/navigating-the-bubble-editor/tools/using-the-debugger.md)

[^8]: *Timeouts* happen when tasks exceed their maximum allowed execution time and need to be stopped to maintain system stability. This early stop can leave processes incomplete and, in the worst cases, corrupt data. Though rare, timeouts are a potential issue in any programming environment, not just in Bubble.

[^9]: Highly complex in this context generally means operations that involve the database, such as searches with advanced filters that require Bubble to examine each row. These can add a lot of complexity and demand on system resources.

[^10]: *Workload* is the overall metric that measures how much work the server has to do to power your app.\
    **Article series:** [Workload](https://manual.bubble.io/help-guides/workload.md)
