Error Handlers

Standard Support for Mule 4.1 ended on November 2, 2020, and this version of Mule will reach its End of Life on November 2, 2022, when Extended Support ends.

Deployments of new applications to CloudHub that use this version of Mule are no longer allowed. Only in-place updates to applications are permitted.

MuleSoft recommends that you upgrade to the latest version of Mule 4 that is in Standard Support so that your applications run with the latest fixes and security enhancements.

From a high-level perspective, errors that occur in Mule fall into one of two categories: system errors and messaging errors.

Messaging Errors

Mule throws a messaging error (a Mule error) whenever a problem occurs within a flow. To handle Mule errors, you can set up On Error components inside the scope-like Error Handler component. By default, any unhandled errors are logged and propagated.

When a Mule Event that is getting processed through a Mule flow raises an error, the normal flow execution stops, and the process is transferred to the Error Handler component. Inside the Error Handler component, you set up On Error components to match error types and expressions. Within each On Error component, the error path you define can incorporate any number of event processors to handle the error as precisely as you want. The Error Handler component will route an error to the first On Error scope that matches the error.

This figure shows what happens when an event processor throws a Mule error:

error handling 39be7

You can override the default error handling behavior either per flow or within a flow. You can group a sequence of components together into a Try Scope to further override the flow’s error handling behavior. The default Error Handler can also be customized with a reference to the desired handler in the app’s configuration.

This example sets a default payload for all unhandled errors:

Example: XML Configuration for the App
<configuration defaultErrorHandler-ref="allErrorHandler"/>

<error-handler name="allErrorHandler">
        <set-payload value="#['An unhandled error occurred: ' ++ error.description]"/>

Just as you can reference error handlers to specify the default, error handlers can also be referenced in flows.

This example sets up a flow with an Error Handler that logs all errors through a reference:

Example: XML Configuration for the App
<on-error-continue name="loggingErrorHandler">
    <logger message="#['Error: ' ++ error.description]"/>

<flow name="withSharedHandler">
    <http:request url=""/>
    <error-handler >
        <on-error ref="loggingErrorHandler"/>

System Errors

Mule throws a system error when an exception occurs at the system level.

If no Mule Event is involved, the errors are handled by a system error handler.

A system error handler handles exceptions that occur:

  • During application start-up.

  • When a connection to an external system fails.

When a system error occurs, Mule sends an error notification to registered listeners, logs the error, and if the error was caused by a connection failure, executes a reconnection strategy.

System error handlers are not configurable in Mule.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub