Error Handling

Errors are used to model exceptional process paths. With an error, the happy path of a process is left. An error is caught by an Error Boundary Event or Error Start Event if their Error Code pattern matches the Error Code.

  • Errors are divided into technical errors (e.g. database connection problem) or business errors (e.g. approval declined).

  • An error is defined by an Error Code.

  • The error may be caught by an Error Boundary Event attached to the activity or subprocess, or by an Error Start.

  • An Error Boundary Event or Error Start Event with an empty Error Code catches every error.

Error Codes

Error codes are defined as strings. They can be refined by inserting a colon (:). Multiple sub-error codes can be caught using wildcards (*). Trailing wildcards are optional so the string custom:error is the same as custom:error:*.


If the error code booking:failed is thrown it can be caught with following error code patterns: booking:failed, booking , *:failed . Additionally, you can catch it by specifying an empty error code. This catches all errors.

System Errors

System errors are thrown by process elements like a Database Step or a Web Service Call Step. Their error codes are set by default and are prefixed with ivy (e.g. ivy:error:database).

Throwing Errors

An error can be thrown explicitly by an Error End Event, or from code executed in IvyScript or Java. System errors (e.g. ivy:error:database) are implicitly thrown by the system.

Error End Event

The happy path of a process is left if an error is thrown with a Error End (e.g. if approval has been declined). The Error End Event throws the error to the upper process level, it can’t be caught on the same process level.


Error End Events can also be used to re-throw a pre-defined Axon Ivy error with a specific error that has a meaning to the business (e.g. if a web service is not available).


Error Handling in an HTML Dialog

When an error occurs inside of an HTML Dialog the handling is slightly different than the default error handling.

Default HTML Dialog Error Handling

Any error thrown (e.g. a Java exception) is handled inside of the HTML Dialog. Therefore, there is no propagation to the caller process or between Ivy/JSF composites. It is important to handle errors locally in the Dialog Logic to let the user work uninterrupted on the same dialog.

Exit an HTML Dialog by an Error End Element

It is possible to exit an HTML Dialog by an Error End Element. This is useful to leave the happy path of the calling business process. The throwing Error End Element must be located in the HTML Dialog Logic of an HTML Dialog Page (not a Component).


IvyScript or Java Code

Unhandled Script Exception

If an unhandled exception occurs while executing IvyScript or Java code then the calling process element throws an error with the Error Code ivy:error:script. On the error object, the causing Java exception is available as the technical cause.

Throwing an Error Programmatically

An error with a certain Error Code can be thrown using the following IvyScript code:

import ch.ivyteam.ivy.bpm.error.BpmError;


To throw an error with a certain Error Code, use the following Java code:

import ch.ivyteam.ivy.bpm.error.BpmError;

throw BpmError.create("mystock:empty").build();

Elements Throwing System Errors

The process elements Program Interface, Database, WebService, and E-Mail throw system errors. If an exception or timeout occurs on these elements, you can catch it using a matching Error Code or a directly addressed Error Start Event. On the Error Start process element, you can access more information about the error via the variable error and the legacy variable exception.

Catching Errors

Errors can either be caught by Error Boundary Events or Error Start Events.

An error is caught in the following order:

  1. By an Error Start Event directly addressed in the element’s inscription mask (If available on the inscription).

  2. By an Error Boundary Event attached directly to the activity, the error comes from.

  3. By an Error Start Event on the same process level if not thrown by an Error End Event.

  4. By an Error Handling on the next higher process level, starting there with step 2 until the top-level process is reached.

  5. By a Project Error Process in the top-level project.

  6. If the error is not caught it is displayed to the user on the standard Error Pages.


Each process - including the embedded subprocess - is a separate process level.

Error Boundary Event

A Error Boundary Event catches errors that have been thrown from the attaching activity or subprocess if the configured Error Code matches the received error code.


Error Start Event

A Error Start catches unhandled errors which were thrown in the same process or inside a subprocess if the configured Error Code matches the thrown error.


Loop Prevention

To prevent endless process execution caused by an inappropriate error handling, the Ivy process engine detects loops during the error handling. If the engine detects a loop, the error handling will be continued at the next higher process level with the new error code ivy:error:loop, to interrupt the cycle.

Loop detection is done on error-catching elements (Error Start Event and Error Boundary Event). The engine checks if there was already an identical execution of the catcher at this process level. Identical means: Same process request, same throwing element (including its process call stack), and same catching element (including its process call stack).

Let’s illustrate this with two use cases:

Use Case 1

A process element throws a BpmError. The Error Boundary Event catches the error and calls the process element again. In this case, the loop detection will interrupt the process when the Boundary Error Event is reached the second time. This would also be the case if the throwing error element is located in a composite or callable process.


Use Case 2

In this case, the loop detection will interrupt the process ‘callInCall1’ after the second error handling. The process will be continued by the error handling on the caller process with the error code ivy:error:loop. The process will end on the End Element named ‘done’.


Project Error Process

A Project Error Process catches uncaught errors from the whole project. The name of a Project Error Process must start with Error and has to reside in the top-level process group Processes. It can contain one or more Error Start Events.


The process data of the throwing process (i.e. the value of the in variable) is not available in the Error Start of a Project Error Process.

Error Object

The error object provides the following information about the error that was caught:

  • Unique Error ID

  • Error Code

  • Technical Cause (Java Exception)

  • Process element

  • Process call stack

  • User-defined error attributes

Refer to the Public API of BpmError for detailed information.