Business Errors vs. Technical Errors

A BPMN error is meant for business errors - which are different than technical exceptions. So, this is different than Java exceptions - which are, by default, handled in their own way.

You might also want to check out the basics of in the User Guide first.

Defining an Error

An error event definition references an error element. The following is an example of an error end event, referencing an error declaration:

You can trigger this error event either with a throwing error event within your process definition or from Delegation Code, see theThrowing BPMN Errors from Delegation Code section of the for more information.

Another possibility to define an error is setting of the type (class name) of any Java Exception as error code. Example:

An error event handler references the same error element to declare that it catches the error.

Error Start Event

An error start event can only be used to trigger an Event Sub-Process - it cannot be used to start a process instance. The error start event is always interrupting.

Three optional attributes can be added to the error start event: , camunda:errorCodeVariable and :

  • If errorRef is omitted, the subprocess will start for every error event that occurs.
  • The camunda:errorCodeVariable will contain the error code that was specified with the error.
  • The camunda:errorMessageVariable will contain the error message that was specified with the error.
    camunda:errorCodeVariable and can be retrieved like any other process variable, but only if the attribute was set.

Error End Event

When process execution arrives at an error end event, the current path of execution is ended and an error is thrown. This error can be caught by a matching intermediate error boundary event. In case no matching error boundary event is found, the execution semantics defaults to the none end event semantics.

Error Boundary Event

An intermediate catching error event on the boundary of an activity, or error boundary event for short, catches errors that are thrown within the scope of the activity on which it is defined.

When an error event is caught, the activity on which the boundary event is defined is destroyed, also destroying all current executions therein (e.g., concurrent activities, nested subprocesses, etc.). Process execution continues following the outgoing sequence flow of the boundary event.

A error boundary event is defined as a typical boundary event. As with the other error events, the errorRef references an error defined outside of the process element:

The errorCode is used to match the errors that are caught:

  • In case an errorRef is provided and it references an existing error, the boundary event will only catch errors with the defined error code.
  • If the errorCodeVariable is set, the error code can be retrieved using this variable.
  • If the errorMessageVariable is set, the error message can be retrieved using this variable.

    Unhandled BPMN Error

It can happens that no catching boundary event was defined for an error event. The default behaviour in this case is to log information and end the current execution.This behaviour can be changed with enableExceptionsAfterUnhandledBpmnError property set to (via the process engine configuration or the deployment descriptor) and Process Engine Exception will be thrown if unhandled BPMN Error occurs.

Catch and Re-Throw Pattern

An error can be handled by the error start event in the event sub process and the same error can be thrown from the event sub process to handle the error on the higher level scope (in the example below, the error thrown from the Event Subprocess is handled by the error boundary event in the Subprocess).

Additional Resources