On-Error Error Handlers
When an error occurs in a Mule app, an Error Handler component routes the error to the first On-Error component (On Error Continue or On Error Propagate) configuration that matches the Mule error, such as HTTP:NOT_FOUND, DB:CONNECTIVITY, or ANY (the default for all Mule errors). If no error handling is configured for the error, the app follows a default error handling process.
On-Error components differ in the way they affect their owner, that is, the Flow or Try scope where they are defined.
- On Error Propagate
Executes but propagates the error to a higher level, such as a containing scope (for example, to a Flow that contains a Try scope where the error occurs) or external flow containing a Flow Reference to the flow in which an error occurs. The error breaks the owner’s execution and propagates to that higher level, causing a failure at that level. In addition, any transaction the owner handles is rolled back. However, note that the transaction is not rolled back if another component (one that does not own On Error Propagate) created the transaction.
- On Error Continue
Executes and uses the result of the execution as the result of its owner, as if the owner completed the execution successfully. Any transaction the owner handles is committed. However, note that the transaction is not committed if another component (one that does not own On Error Propagate) created the transaction.
To help you identify and handle potential errors when designing a Mule app, On-Error components list the errors that the runtime engine and operations configured in the app can throw. You can select the errors you want to handle.
Matching: On-Error components can perform matching based on error types you select. The list of selectable error types depends on the module and connector operations within the flow or scope to which the On-Error component applies. It also lists
STREAM_MAXIMUM_SIZE_EXCEEDEDerrors, which the runtime can throw.
Matching expression (for more advanced use cases): You can perform error matching based on a
whencondition that you define in the When field of an On-Error component. For example, you might map the component to fatal errors, which have error messages that contain the word "fatal":
When field configuration in the UI:
error.cause.message contains "fatal"
XML configuration example:
<on-error-continue enableNotifications="true" logException="true" doc:name="On Error Continue" type="ANY" when='error.cause.message contains "fatal"'/>
Note that matching conditions are evaluated sequentially, in the order in which the On-Error components reside in the Error Handler. So, for example, if you want to handle specific HTTP errors in one way but handle all other errors a different way, you need to provide an On-Error component configuration for the HTTP errors before a component that captures the remaining errors with ANY. Keep in mind that default error handling takes place for errors you that you do not explicitly match or use ANY to capture. The default error handler logs and propagates such unhandled errors.
By default, On-Error components also log matching errors and enable error notifications for occurrences of the errors. You can disable those settings through the XML.
In most cases, you configure On-Error components within the scope-like Error Handler component. Though each flow contains only one built-in Error Handler, the Error Handler can contain as many On-Error components as you require, and each On-Error component can contain any number of other components, such as Loggers and other components that you configure to handle errors captured by the On-Error component.
Because an Error Handler component is built into Flow and Try components, you can use On-Error components for errors that occur within the scope of a flow or within a Try component. For examples, see Using On-Error Components to Handle Messaging Errors.
You can also use On-Error components in a separate Error Handler configuration that is referenced from a Flow component or Try scope (see Referencing a Global Error Handler).
Within a flow’s built-in Error Handler component, you can set up one or more
On Error components to match error types and expressions. The following example
outlines the general structure for handling errors that occur within a given
flow. One flow uses On Error Continue (
on-error-continue) in its Error Handler
component. The other flow uses On Error Propagate (
<flow name="catch"> <!-- flow logic --> <error-handler> <on-error-continue> <!-- error handling logic --> </on-error-continue> </error-handler> </flow> <flow name="rollback"> <!-- flow logic --> <error-handler> <on-error-propagate> <!-- error handling logic --> </on-error-propagate> </error-handler> </flow>
For examples, see Using On-Error Components to Handle Messaging Errors.
Just as you can share error handlers by exposing them globally and referencing them in flows and try scopes, you can also reuse On-Error components. You can define and name an On-Error component globally and then reference from an Error Handler component.
<on-error-propagate name="sharedPropagateHandler"> <logger message="An unhandled error has occurred."/> </on-error-propagate> <on-error-continue type="EXPRESSION" name="sharedContinueHandler"> <logger message="An expression failed to evaluate."/> </on-error-continue> <error-handler name="reusingHandlers"> <on-error ref="sharedContinueHandler"/> <on-error-continue type="ROUTING"> <logger message="An expression failed to evaluate."/> </on-error-continue> <on-error ref="sharedPropagateHandler"/> </error-handler>
For other reuse examples, see Referencing a Global Error Handler.