---
title: "On-Error Flows"
slug: "on-error-flows"
updated: 2026-05-06T16:05:38Z
published: 2026-05-06T19:13:29Z
canonical: "help.hyperscience.ai/on-error-flows"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# On-Error Flows

> [!WARNING]
> **Accessing this feature**
> 
> Your access to the feature described in this article depends on your license package and pricing plan.
> 
> To learn which features are available to your organization and how to add more, contact your Hyperscience representative.

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 included on-error flow sends 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
```
{
"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](/v43/docs/testing-and-debugging-flows).

![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/OnErrorFlowSubmissionObjectV42.png)

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 included 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](/v43/docs/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 v43, 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.

## Versions of the on-error flow

The version of the on-error flow included included in your instance depends on the version of Hyperscience you are running:

- **Hyperscience v38-v41** — “On-Error with included Submission data”
- **Hyperscience v42.0.x** — “On-Error with included Submission data V2”
- **Hyperscience v42.1.x and later** — “On-Error with included Submission data V3”

### On-Error with included Submission data V2

This version uses the updated Flow Runs endpoints of our API, which allow flow-run data to be retrieved at a more granular level and can help improve application responsiveness when viewing flow runs.

> [!NOTE]
> **You can continue to use the first and second versions of the “On-Error with included Submission data” flow in v43.** However, we recommend upgrading to v3 of the flow, as the first version will be deprecated in a future version of Hyperscience.

### On-Error with included Submission data V3

The third version builds on the improvements made in the second version and consists of a top-level flow (“On-Error with included Submission data V3”) and a read-only subflow (“Retrieve error and submission information”). This structure is similar to that of the included “Document Processing” flow and streamlines the flow-upgrade process in future versions of Hyperscience. Therefore, we recommend upgrading to this version of the “On-Error with included Submission data” flow as soon as possible.

## Creating an on-error flow

Each Hyperscience version includes one out-of-the-box on-error flow (“On-Error with included Submission data V3” in v43), but you can create additional on-error flows by:

- duplicating an "On-Error with included Submission data" flow (to learn how, see [Managing Flows](/v43/docs/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 flows included in v43. 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 Flows page (**Flows** > **Flows**), find the on-error flow that you would like to configure, and click on its name (e.g., “On-Error with included Submission data V3”).
2. Click on **JSON Outputs**, and click **Add** in the block settings. ![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/V421OnErrorJSONOutputs.png)
3. Select either **HTTP Notifier** or **Message Queue Notifier**, and follow the instructions in either [HTTP Notifier](/v43/docs/http-notifier) or [Message Queue Notifier](/v43/docs/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 Flows page (**Flows** > **Flows**), find the top-level flow you want to assign an on-error flow to, and click on its name.
2. Click **Edit Flows**.
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. ![](https://cdn.us.document360.io/87894cef-4958-4f3f-be6f-b75a78c82548/Images/Documentation/V421IfFlowFails.png)

1. 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 Flows page (**Flows** > **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.