Mule Exception Strategies

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

errors

Mule provides numerous options for handling errors. Errors, or faults, that occur within Mule are referred to as exceptions; when an activity in your Mule instance fails, Mule throws an exception. To manage these exceptions, Mule allows you to configure exception strategies.

Mule’s default exception strategy — which implicitly applies to all Mule applications — manages errors (such as, thrown exceptions) in Mule flows. When your flows require more sophisticated error management, you can implement one or more exception strategies to construct precise, efficient protocols for handling errors.

From a high level perspective, errors that occur in Mule fall into one of two categories: System Exceptions, and Messaging Exceptions.

System Exceptions

Mule invokes a System Exception Strategy when an exception is thrown at the system-level (that is, when no message is involved, exceptions are handled by system exception strategies). For example, system exception strategies handle exceptions that occur:

During application start-up
When a connection to an external system fails

When a system exception occurs, Mule sends an exception notification to registered listeners, logs the exception, and — if the exception was caused by a connection failure — executes the reconnection strategy. System Exception Strategies are not configurable in Mule.

As an example, imagine Mule establishes a connection to a JMS broker in order to receive a message. When Mule attempts to use the connection to consume a message the connection fails, which causes Mule to invoke the system exception strategy. Because the failure occurred before any message was received for processing, Mule invoked the system, rather than messaging, exception strategy.

Messaging Exceptions

Mule invokes a Messaging Exception Strategy whenever an exception is thrown within a flow. Whenever a message is involved, exceptions are handled by messaging exception strategies.

When a message being processed through a Mule flow throws an exception, normal flow execution stops. Mule transfers the message to the message processor sequence within the exception strategy. You can incorporate any number of message processors into an exception strategy to handle the exception precisely as you wish. The diagram below illustrates what happens when a message throws an exception.

Mule supports five types of messaging exception strategies, each of which is capable of handling errors that occur in flows which process transactions:

Exception Strategy	Use	Transaction Error Handling
Catch Exception Strategy	Customizes the way Mule handles any exception. Catch exception strategies consume inbound messages, as opposed to rolling them back.	When a message throws an exception, the catch exception strategy always commits the transaction and consumes the message.
Choice Exception Strategy	Customizes the way Mule handles a message that throws an exception based on the message’s content at the moment it throws the exception.	When a message throws an exception, the choice exception strategy makes a decision about where to route the message for further processing. (The choice exception strategy itself never actually performs any rollback, commit, or consume activities.)
Default Exception Strategy	Provides an implicit default to handle all messaging exceptions that are thrown in Mule applications	When an exception is thrown in a flow, Mule automatically rolls back any pending transaction and logs the exception; if no transaction is involved, the default exception strategy simply logs the exception.
Reference Exception Strategy	Refers and adheres to the error handling parameters defined in a global catch, rollback, or choice exception strategy.	When a message throws an exception, the reference exception strategy refers and adheres to the error handling parameters defined in a global catch, rollback, or choice exception strategy. (The reference exception strategy itself never actually performs any rollback, commit, or consume activities.)
Rollback Exception Strategy	Ensures that a message that throws an exception in a flow is rolled back for reprocessing (if the message source supports redelivery). Rollback exception strategies do not consume inbound messages.	When a message throws an exception, the rollback exception strategy makes one or more attempts to rollback the message and redeliver it for processing (if the message source supports redelivery). If the message exceeds its redelivery attempts, then the rollback exception strategy commits the failed transaction and consumes the message.

Exception Strategy

Use

Transaction Error Handling

Catch Exception Strategy

Customizes the way Mule handles any exception. Catch exception strategies consume inbound messages, as opposed to rolling them back.

When a message throws an exception, the catch exception strategy always commits the transaction and consumes the message.

Choice Exception Strategy

Customizes the way Mule handles a message that throws an exception based on the message’s content at the moment it throws the exception.

When a message throws an exception, the choice exception strategy makes a decision about where to route the message for further processing. (The choice exception strategy itself never actually performs any rollback, commit, or consume activities.)

Default Exception Strategy

Provides an implicit default to handle all messaging exceptions that are thrown in Mule applications

When an exception is thrown in a flow, Mule automatically rolls back any pending transaction and logs the exception; if no transaction is involved, the default exception strategy simply logs the exception.

Reference Exception Strategy

Refers and adheres to the error handling parameters defined in a global catch, rollback, or choice exception strategy.

When a message throws an exception, the reference exception strategy refers and adheres to the error handling parameters defined in a global catch, rollback, or choice exception strategy. (The reference exception strategy itself never actually performs any rollback, commit, or consume activities.)

Rollback Exception Strategy

Ensures that a message that throws an exception in a flow is rolled back for reprocessing (if the message source supports redelivery). Rollback exception strategies do not consume inbound messages.

When a message throws an exception, the rollback exception strategy makes one or more attempts to rollback the message and redeliver it for processing (if the message source supports redelivery). If the message exceeds its redelivery attempts, then the rollback exception strategy commits the failed transaction and consumes the message.

Characteristics of Messaging Exception Strategies

Each flow can contain only one exception strategy.
Each exception strategy can contain any number of message processors.
Choice exception strategies can contain one or more catch and/or rollback exception strategies. (Rollback and catch exception strategies cannot, however, contain other exception strategies.)
You can create one or more global exception strategies to reuse in flows throughout your entire Mule application.
A Transactional Scope may include its own exception strategy, regardless of what you define at Flow level.

Examples

<mule xmlns:spring="http://www.springframework.org/schema/beans"
    xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.mulesoft.org/schema/mule/http
	http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
	http://www.springframework.org/schema/beans
	http://www.springframework.org/schema/beans/spring-beans-current.xsd
	http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd">
<http:listener-config name="HTTP_Listener_Configuration"
host="0.0.0.0" port="11081" doc:name="HTTP Listener Configuration"/>
<flow  name="loan-broker-sync">
        <description>
            The main loan broker flow:
            1) Receives a customer request
            2) Performs a lookup of the customer credit profile using a component
            binding
            3) Determines the bank that should be used to request quotes
            4) Sends the request to the selected banks and aggregates responses
            5) Selects the lowest quote from the list of quotes
            6) Returns the response to the client
        </description>
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <choice doc:name="Choice">
            <when expression="!(payload.name == null || payload.ssn == null || payload.amount == null || payload.term == null)">
                <expression-component doc:name="create customer request">
<![CDATA[import org.mule.example.loanbroker.message.CustomerQuoteRequest;
import org.mule.example.loanbroker.model.Customer;
payload = new CustomerQuoteRequest(new Customer(payload.name, Integer.parseInt(payload.ssn)),
Integer.parseInt(payload.amount), Integer.parseInt(payload.term));]]></expression-component>
                <enricher doc:name="Enrich with creditProfile" source="#[payload]"
target="#[flowVars.creditProfile]">
                    <flow-ref doc:name="lookupCustomerCreditProfile" name="loan-broker-sync"/>
                </enricher>
                <enricher doc:name="Enrich with banks" source="#[payload]"
target="#[flowVars.banks]">
                    <flow-ref doc:name="lookupBanks" name="loan-broker-sync"/>
                </enricher>
                <set-variable doc:name="create empty quotes"
value="#[new java.util.LinkedList()]" variableName="quotes"/>
                <foreach collection="#[flowVars.banks]" doc:name="Foreach">
                    <enricher doc:name="Message Enricher" target="#[quotes.add($)]">
                        <flow-ref doc:name="lookupLoanQuote" name="loan-broker-sync"/>
                    </enricher>
                </foreach>
                <flow-ref doc:name="findLowestLoanQuote" name="loan-broker-sync"/>
                <object-to-string-transformer doc:name="Object to String"/>
            </when>
            <otherwise>
                <expression-component doc:name="set error message">
                <![CDATA[payload="Error: incomplete request"]]></expression-component>
            </otherwise>
        </choice>
        <catch-exception-strategy doc:name="Catch Exception Strategy">
            <set-payload doc:name="Set error message" value="Error processing loan request"/>
        </catch-exception-strategy>
    </flow>
</mule>

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs