Mule Exception Strategies

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can 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 (i.e., 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
Default exception strategy	Implicitly applied by 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.
Catch exception strategy	Define a catch exception strategy to customize 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.
Rollback exception strategy	Define a rollback exception strategy to ensure 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.
Reference exception strategy	Define a reference exception strategy to refer and adhere 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.)
Choice exception strategy	Define a choice exception strategy to customize 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.)

Exception Strategy

Use

Transaction Error Handling

Default exception strategy

Implicitly applied by 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.

Catch exception strategy

Define a catch exception strategy to customize 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.

Rollback exception strategy

Define a rollback exception strategy to ensure 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.

Reference exception strategy

Define a reference exception strategy to refer and adhere 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.)

Choice exception strategy

Define a choice exception strategy to customize 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.)

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">
...
<http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="11081" doc:name="HTTP Listener Configuration"/>
<flow doc:name="loan-broker-sync" name="loan-broker-sync">
        <description>
            The main loanbroker flow that:
            i) Receives a customer request
            ii) Performs a lookup of the customer credit profile using a component
            binding
            iii) Determines the bank that should be used to request quotes
            iv) Sends the request to the selected banks and aggregates responses
            v) Selects the lowest quote from the list of quotes
            vi) 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="lookupCustomerCreditProfile"/>
                </enricher>
                <enricher doc:name="Enrich with banks" source="#[payload]" target="#[flowVars.banks]">
                    <flow-ref doc:name="lookupBanks" name="lookupBanks"/>
                </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="lookupLoanQuote"/>
                    </enricher>
                </foreach>
                <flow-ref doc:name="findLowestLoanQuote" name="findLowestLoanQuote"/>
                <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