Throw Error

Concept

BPMN 2.0 workflows are a concept feature. They're still being developed and can change before they're released. They're available only when the site's license includes the Concept feature Bpmn2.

Audience: Low-code Engineers

Skill Prerequisites: Actions, Conditions, Workflows

Raises an error with a code and a message. In a BPMN 2.0 workflow, an error event with the same code on the task's border decides what happens next. Anywhere else, the error stops the actions as any error does.

Typical Use Cases

• Send a BPMN 2.0 workflow down an error path drawn on its diagram, for example to a task that asks a buyer to check a supplier when the supplier is unknown
• Fail a workflow with a code that the error events of a call activity calling it can match
• Stop the actions with an error in any action list, to trigger the On Error actions of an enclosing Execute Actions

Don't use it to

• Show different messages to administrators and to end users. Use Throw Exception, which has an Admin Message and a Friendly Message.
• Show a normal validation message on a form. Use Display Error Message or field validation instead.
• Stop without an error. Use Stop Execution instead.

Related Actions

Action Name	Description
Throw Exception	Raises an error without a code, with separate messages for administrators and end users.
Execute Actions	Catches the error with its On Error actions.
Raise Event	Tells a waiting BPMN 2.0 workflow that something happened, without an error.
Stop Execution	Stops the remaining actions without raising an error.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Error Code	A short code that error events match, for example PAYMENT_DECLINED. Error events compare it exactly, including case. Leave it empty for an error without a code, which only an error event that catches every error catches.	Yes	empty string	No
Message	What went wrong, in words the person reading it can act on. It's the value of [ExceptionMessage] after an error event or an On Error list catches the error. When it's empty, the message is The workflow raised the error "CODE". with the code, or The workflow raised an error. without one.	Yes	empty string	No

How the error is handled

The error goes to the first of these that can handle it:

1. The On Error actions of an action around it, such as Execute Actions, as for any error.
2. In a BPMN 2.0 workflow, once the error leaves the task's actions: the error event on the task's border with the same code, then one that catches every error, then the error events on the border of the subprocesses around the task. The run continues along that error event's path, with [ExceptionCode] and [ExceptionMessage] set. See Errors.
3. Otherwise the run fails. In a BPMN 2.0 workflow, the message names the task, the code and the message, for example "Check supplier" raised the error "SUPPLIER_UNKNOWN", and no error event caught it: Fabrikam isn't an approved supplier. On the current engine and in forms, APIs and other action lists, the error stops the actions as any error does.

Considerations

• One message for everyone. Unlike Throw Exception, there's no separate Friendly Message: where end users see the error, they see this Message. Keep technical details, such as ids or SQL, out of it.
• Add a condition. Without a condition, the action always fails. Put the rule in the action's Condition. See Common Parameters.
• Codes are exact. Payment_Declined doesn't match an error event set to PAYMENT_DECLINED.
• Handled before the diagram sees it. An action's own On Error, or Continue On Error, inside the task handles the error first, and then the task's error events never see it.
• Licensing. The action needs only the Concept feature Bpmn2. It works in any action list on either workflow engine.
• On the diagram. A BPMN 2.0 workflow can also raise an error with an error end event, without an action. See Errors.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Send a request with an unapproved supplier down the error path

In a task of a BPMN 2.0 workflow, this action raises SUPPLIER_UNKNOWN when the SupplierApproved token isn't true. An error event set to Only the error with this code and SUPPLIER_UNKNOWN on the task's border takes the run to the steps that handle it, where [ExceptionMessage] holds the message.

{
    "Title": "Throw Error",
    "ActionType": "Flow.ThrowError",
    "Description": "Stop when the supplier isn't approved",
    "Condition": "[SupplierApproved] != \"true\"",
    "Parameters": {
        "ErrorCode": "SUPPLIER_UNKNOWN",
        "Message": "[Supplier] isn't an approved supplier."
    }
}

Revised 11/12/2026