# On-Error Flows

- Updated on May 5, 2026  
- Published on Sep 16, 2024  
- 4 minute(s) read

When a failing submission has exhausted all of its flow blocks’ retry attempts, it will have a Halted status and a Failed flow run. To alert members of your organization of the Failed flow run, you can choose an _on-error flow_ for each of your flows.

The default on-error flow will send a notification that contains information about the failed flow run via an HTTP Output or Message Queue Notifier connection. If the flow run was processing a submission, the notification will also include a _submission_ object with information about the submission being processed:

### JSON

````json
{
  "flow_run": {...}, // https://docs.hyperscience.ai/#flow-run-object
  "submission": {...} // https://docs.hyperscience.ai/#submission-objects
}
````

In the screenshot below, the _submission_ object in the flow’s output is shown on the Flow Run page. To learn more about the options available on this page, see [Testing and Debugging Flows](https://help.hyperscience.ai/general-information/docs/v39-testing-and-debugging-flows).

The recipients of the notification can use the data provided to troubleshoot the error. If additional information is required, they can use the _submission id_ in the notification to find the submission’s details page in the application ( _<application_url>/submissions/<submission_id>_). If needed, they can then take action to process the flow’s submission using some other method. In this way, on-error flows can help your organization meet SLAs for time-sensitive submissions.

If the default on-error flow does not meet the needs of your organization, you can create a custom on-error flow with the Flows SDK. For more details, see [Creating an on-error flow](https://help.hyperscience.ai/general-information/docs/v39-on-error-flows#creating-an-onerror-flow).

As a best practice, we recommend selecting an on-error flow for each of your top-level flows. You can select an on-error for flow for any flow in v39, regardless of whether that flow was created in previous versions or whether it processes submissions or Unstructured documents.

Note that on-error flows are not meant to replace an observability stack; they are designed to complement existing monitoring tools by proactively notifying your organizations of failed flow runs.

- **Example:** If submissions are failing due to critical infrastructure issues, such as a database malfunction, the on-error flow will also not run. The issue preventing the on-error flow from running—and causing submissions to fail—cannot be detected without other system-monitoring tools in place.

## Creating an on-error flow

V39 includes one out-of-the-box on-error flow ("On-Error with included Submission data V39"), but you can create additional on-error flows by:

- duplicating "On-Error with included Submission data V39" (to learn how, see [Managing Flows](https://help.hyperscience.ai/general-information/docs/v39-managing-flows#duplicate-a-flow-or-flow-group)), or
- creating one from scratch with the Flows SDK.

- Flow developers can designate a flow as an on-error flow by setting its _roles_ value to _on_error_. For more information, see the [Flows SDK documentation](https://flows-sdk.hyperscience.ai/pages/source-docs.html#flows_sdk.flows.Manifest).

## Configuring the output connection for an on-error flow

Before you use an on-error flow, you need to set up the output connection that it should use to send notifications.

The instructions below apply to the on-error flow included in v39. If you're setting up an on-error flow that your organization's developers created, the block names and available connection options may differ.

To set up the output connection:

1. Go to the All Flows page ( **Flows** > **All Flows**), find the on-error flow that you would like to configure, and click on its name.
2. Click on the JSON Outputs block, and click **Add** in the block settings.

3. Select either **HTTP Notifier** or **Message Queue Notifier**, and follow the instructions in either [HTTP Notifier](https://help.hyperscience.ai/general-information/docs/v39-http-notifier) or [Message Queue Notifier](https://help.hyperscience.ai/general-information/docs/v39-message-queue-notifier) to finish configuring the connection.

## Assigning an on-error flow

In order for an on-error flow to run after another flow fails, you need to select the on-error flow in the If Flow Fails section in that flow's settings.

You can assign on-error flows to both top-level flows and subflows. If a subflow and a top-level flow in a flow group have on-error flows assigned to them, and the subflow exhausts its retry attempts, the on-error flows for both the subflow and the top-level flow will run.

### Assign an on-error flow to a top-level flow

1. On the Top-level Flows page ( **Flows** > **Top-level Flows**), find the top-level flow you want to assign an on-error flow to, and click on its **Open** **→** link.
2. In the table on the flow details page, click on the name of the top-level flow.
3. In Flow Studio, scroll down the left-hand sidebar to find the If Flow Fails section. In the **Flow to Run** drop-down list, click the name of the on-error flow that you want to run when the flow you're currently viewing fails.
   - If you would like more information about the flow you have chosen, click the **View Flow** link under the drop-down list to see the flow in Flow Studio.
     
     
4. Click **Save** in the upper-right corner of the page.

### Assigning an on-error flow to a subflow

In the application, you can assign on-error flows only to subflows that are not read-only. A _read-only flow_ is a flow that has _read_only_ in its _roles_ property. You can assign on-error flows to these flows through the Flows SDK.

To assign an on-error flow to a subflow that is not read-only:

1. Go to the All Flows page ( **Flows** > **All Flows**), find the flow you want to assign an on-error flow to, and click on its name.
2. In Flow Studio, scroll down the left-hand sidebar to find the If Flow Fails section. In the **Flow to Run** drop-down list, click the name of the on-error flow that you want to run when the flow you're currently viewing fails.
   - If you would like more information about the flow you have chosen, click the **View Flow** link under the drop-down list to see the flow in Flow Studio.
3. Click **Save** in the upper-right corner of the page.