Catch Exception Strategy

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.

You can define a catch exception strategy to customize the way Mule handles messages with errors. A catch exception strategy catches all exceptions thrown within its parent flow and processes them, thereby overriding Mule’s implicit default exception strategy.

Mule’s catch exception strategy behavior is similar to a Java catch block, except that you cannot throw a new exception or catch another exception within a catch exception strategy.

When to Use

Use a catch exception strategy to design a unique strategy for handling a message that contains an error. Further, you can use a catch exception strategy to:

Avoid propagating exceptions to inbound connectors
Avoid propagating exceptions to parent flows via Flow Reference Components
Ensure that a transaction processed by the flow does not roll back when an error occurs (that is, the transaction is never rolled back to reattempt processing; Mule commits the transaction.)

For example, suppose you have a flow that processes messages from a JMS queue (a reservation for a flight), enriches them by adding a property acquired from an external resource (seat assignment), and then sends them to another queue. You configure a catch exception strategy to handle errors that occur in this flow; when an error occurs during processing — say the seat information is not available from the external resource — the message throws an exception. The catch exception strategy catches the exception, applies a header to it to advise that “no seats are available,” and pushes the message out of the flow to its next designated queue.

Studio Visual Editor

Studio XML Editor or Standalone

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns:jms="http://www.mulesoft.org/schema/mule/jms" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:spring="http://www.springframework.org/schema/beans" xmlns:core="http://www.mulesoft.org/schema/mule/core"
xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting" xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
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.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/current/mule-jms.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://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd
http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd
http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd ">

    <jms:activemq-connector name="Active_MQ" brokerURL="tcp://localhost:61616" validateConnections="true"
    doc:name="Active MQ"/>

    <flow name="makeReservation" doc:name="makeReservation">
        <jms:inbound-endpoint queue="seatAssigment" connector-ref="Active_MQ" doc:name="Seat assigment queue"/>
        <enricher target="#[flowVars['seatInfo']]" doc:name="Create seatInfo variable with seat assigment">
            <core:processor-chain doc:name="Call seat assigment">
                <http:outbound-endpoint host="localhost" port="1234" path="seatService"
                doc:name="Seat assigment web service"/>
                <http:http-response-to-object-transformer doc:name="Transform response to SeatInfo object"/>
            </core:processor-chain>
        </enricher>
        <set-property propertyName="seatInfo" value="#[flowVars['seatInfo'].getSeatNumber()]"
        doc:name="Set seatInfo jms property"/>
        <jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/>

        <catch-exception-strategy doc:name="Catch Exception Strategy">
            <set-property propertyName="seatInfo" value="No seat info available" doc:name="Set seatInfo jms property"/>
            <jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/>
        </catch-exception-strategy>
    </flow>
</mule>

Configuring a Catch Exception Strategy

Studio Visual Editor

From the Error Handling palette group, drag and drop the Catch Exception Strategy icon into the footer bar of a flow.

Open the Catch Exception Strategy’s Properties Editor, then configure according to the table below.

Field Value

Field	Value
Display Name	Unique name for the exception strategy, if you wish.
Execute When	A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a Choice Exception Strategy. The following states exist for the Execute When field: No expression defined: All messages in this flow that throw exceptions are handled by the catch exception strategy. Expression defined: If the exception strategy evaluates the defined expression against the message being processed and returns `true`, Mule executes the exception strategy. For example, if you enter the following expression, the exception strategy handles only those messages that throw an `org.mule.example.AlreadyProcessedException`. `#[exception.causedBy(org.mule.example.AlreadyProcessedException)]`
Enable Notifications	Checked indicates that Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.
Log Exceptions	Checked indicates that Mule lists exceptions in the console log.

Display Name

Unique name for the exception strategy, if you wish.

Execute When

A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a Choice Exception Strategy.

The following states exist for the Execute When field:

No expression defined: All messages in this flow that throw exceptions are handled by the catch exception strategy.
Expression defined: If the exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy.

For example, if you enter the following expression, the exception strategy handles only those messages that throw an org.mule.example.AlreadyProcessedException.

#[exception.causedBy(org.mule.example.AlreadyProcessedException)]

Enable Notifications

Checked indicates that Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.

Log Exceptions

Checked indicates that Mule lists exceptions in the console log.

The following are sample MEL expressions you can enter in the Execute When field:

#[exception.causedBy(org.mule.example.ExceptionType)]
#[exception.causedExactlyBy(org.mule.example.ExceptionType)]
#[exception.causeMatches('org.mule.example.*')]

#[exception.causeMatches('*') &&
!exception.causedBy(java.lang.ArithmeticException) &&
!exception.causedBy(org.mule.api.registry.ResolverException)]

Save your project.

Drag building blocks from the palette into the Catch Exception Strategy box to build a flow that processes messages that throw exceptions in the parent flow. A catch exception strategy can contain any number of message processors.

You can define only one exception strategy for each flow. If you need to design a more complex error handling strategy that involves more than one way of handling exceptions, consider using a Choice Exception Strategy.

Studio XML Editor or Standalone

To your flow, below all the message processors, add a catch-exception-strategy element. Refer to the code below.

Configure attributes of the exception strategy according to the table below.

Attribute Value

Attribute	Value
doc:name	Unique name for the exception strategy, if you wish. (Not required in Standalone.)
when	A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a Choice Exception Strategy. The following states exist for the `when` parameter: No expression defined: All messages in this flow that throw exceptions are handled by the catch exception strategy. Expression defined: If the exception strategy evaluates the defined expression against the message being processed and returns `true`, Mule executes the exception strategy. For example, if you enter the following expression, the exception strategy handles only those messages that throw an `org.mule.example.AlreadyProcessedException`. `#[exception.causedBy(org.mule.example.AlreadyProcessedException)]`
enableNotifications	`true` or `false` When set to `true`, Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.

doc:name

Unique name for the exception strategy, if you wish. (Not required in Standalone.)

when

A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a Choice Exception Strategy.

The following states exist for the when parameter:

No expression defined: All messages in this flow that throw exceptions are handled by the catch exception strategy.
Expression defined: If the exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy.

For example, if you enter the following expression, the exception strategy handles only those messages that throw an org.mule.example.AlreadyProcessedException.

#[exception.causedBy(org.mule.example.AlreadyProcessedException)]

enableNotifications

true or false

When set to true, Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.

The following are sample MEL expressions you can enter in the when attribute:

#[exception.causedBy(org.mule.example.ExceptionType)]
#[exception.causedExactlyBy(org.mule.example.ExceptionType)]
#[exception.causeMatches('org.mule.example.*')]

#[exception.causeMatches('*') &&
!exception.causedBy(java.lang.ArithmeticException) &&
!exception.causedBy(org.mule.api.registry.ResolverException)]

<flow name="makeReservation" doc:name="makeReservation">
    <jms:inbound-endpoint queue="seatAssigment" connector-ref="Active_MQ" doc:name="Seat assigment queue"/>
    <enricher target="#[flowVars['seatInfo']]" doc:name="Create seatInfo variable with seat assigment">
        <core:processor-chain doc:name="Call seat assigment">
            <http:outbound-endpoint host="localhost" port="1234" path="seatService" doc:name="Seat assigment web service"/>
            <http:http-response-to-object-transformer doc:name="Transform response to SeatInfo object"/>
        </core:processor-chain>
    </enricher>
    <set-property propertyName="seatInfo" value="#[flowVars['seatInfo'].getSeatNumber()]" doc:name="Set seatInfo jms property"/>
    <jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/>
    <catch-exception-strategy doc:name="Catch Exception Strategy" enableNotifications="true" />
</flow>

View the namespace:

<mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns:jms="http://www.mulesoft.org/schema/mule/jms" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:spring="http://www.springframework.org/schema/beans" xmlns:core="http://www.mulesoft.org/schema/mule/core"
xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting" xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
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.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/current/mule-jms.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://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd
http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd
http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">

+ . Add message processors as child elements of the catch-exception-strategy to build a flow that processes messages that throw exceptions in the parent flow. A catch exception strategy can contain any number of message processors. Refer to sample code below in which a set-property and jms:outbound-endbpoint process exceptions.

<flow name="makeReservation" doc:name="makeReservation">
...
    <catch-exception-strategy doc:name="Catch Exception Strategy">
        <set-property propertyName="seatInfo" value="No seat info available" doc:name="Set seatInfo jms property"/>
        <jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/>
    </catch-exception-strategy>
</flow>

Creating a Global Catch Exception Strategy

You can create one or more global exception strategies to reuse in flows throughout your entire Mule application. First, create a global catch exception strategy, then add a Reference Exception Strategy to a flow to apply the error handling behavior of your new global catch exception strategy.

Before creating a Global Catch Exception Strategy, you must have first created a catch exception strategy as described in Configuring a Catch Exception Strategy. The global version of the exception strategy requires copying text from your current exception strategy to create the global file.

Studio Visual Editor

Click File > New > Mule Configuration File. You can use this configuration file to store the building blocks to share with all the flows in your project. This file appears in your Studio project under src/main/app. For this example, it’s called global.xml. The configuration file has the same elements the same as a Mule project so you can search for and drag building blocks into the configuration file.
Click Message Flow and copy the building blocks you want in the configuration file. The catch exception strategy should be in the configuration file.

For example, if the original flow contained a Catch Exception Strategy and an HTTP connector, add these elements to the configuration file.
Save your project.

You can now reference your global file from other flows as described in Applying a Global Catch Exception Strategy to a Flow.

Studio XML Editor or Standalone

Above all the flows in your application, create a catch-exception-strategy element.

To this global catch-exception-strategy element, add the attributes according to the table below. Refer to code sample below.

Attribute Value

Attribute	Value
name	Unique name for the exception strategy, if you wish.
when	A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a Choice Exception Strategy. The following states exist for the `when` parameter: * No expression defined: All messages in this flow that throw exceptions are handled by this catch exception strategy. * Expression defined: When a choice exception strategy evaluates the defined expression against the message being processed and returns `true`, Mule executes the exception strategy. For example, if you enter the following expression, the exception strategy handles only those messages that throw an `org.mule.example.AlreadyProcessedException`. [source,mel] ---- #[exception.causedBy(org.mule.example.AlreadyProcessedException)] ----
enableNotifications	`true` or `false` - When set to `true`, Mule sends an exception notification to a registered listener such as the Mule Management Console whenever the catch exception strategy handles an exception. Default is `true`.
logException	`true` or `false` - When set to `true`, determines whether to log the handled exception to its standard logger in the ERROR level before being handled. Default is `true`.

name

Unique name for the exception strategy, if you wish.

when

A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a Choice Exception Strategy.

The following states exist for the when parameter:

* No expression defined: All messages in this flow that throw exceptions are handled by this catch exception strategy. * Expression defined: When a choice exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy.

For example, if you enter the following expression, the exception strategy handles only those messages that throw an org.mule.example.AlreadyProcessedException.

[source,mel] ---- #[exception.causedBy(org.mule.example.AlreadyProcessedException)] ----

enableNotifications

true or false - When set to true, Mule sends an exception notification to a registered listener such as the Mule Management Console whenever the catch exception strategy handles an exception. Default is true.

logException

true or false - When set to true, determines whether to log the handled exception to its standard logger in the ERROR level before being handled. Default is true.

<catch-exception-strategy name="Catch_Exception_Strategy"/>

<flow name="Creation1Flow1" doc:name="Creation1Flow1">
    <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/>
    <cxf:jaxws-service doc:name="SOAP"/>
...
</flow>

View the Namespace

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf"
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.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://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/current/mule-cxf.xsd">

Add message processors as child elements of the catch-exception-strategy to build a flow that processes messages that throw exceptions in the parent flow. A catch exception strategy can contain any number of message processors. Refer to sample code below in which a simple logger processes exceptions.

<catch-exception-strategy name="Catch_Exception_Strategy">
   <logger message="#[payload]" level="INFO" doc:name="Logger"/>
</catch-exception-strategy>

<flow name="Creation1Flow1" doc:name="Creation1Flow1">
    <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/>
    <cxf:jaxws-service doc:name="SOAP"/>
...
</flow>

Applying a Global Catch Exception Strategy to a Flow

Use a reference exception strategy to instruct a flow to employ the error handling behavior defined by your global catch exception strategy. In other words, you must ask your flow to refer to the global catch exception strategy for instructions on how to handle errors.

Studio Visual Editor

From the Error Handling palette group, drag and drop the Reference Exception Strategy icon into the footer bar of a flow.

Open the Reference Exception Strategy’s Properties Editor, use the drop-down to reference the global catch exception strategy (below); click anywhere on the canvas to save.

You can append a Reference Exception Strategy to any number of flows in your Mule application and instruct them to refer to any of the global catch, rollback or choice exception strategies you have created. You can direct any number of reference exception strategies to refer to the same global exception strategy.

You can create a global catch exception strategy (that is, access the Choose Global Type panel) from the reference exception strategy’s properties editor. Click on the (plus) button next to the Global Exception Strategy drop-down combo box and follow the steps above to create a global catch exception strategy.

+ image::reference-exception-2.png[reference+exception+2]

Studio XML Editor or Standalone

To your flow, below all the message processors, add an exception-strategy element.
To the exception-strategy element, add attributes according to the table below. Refer to code below.

Attribute Value

ref

Name of the global catch-exception-strategy in your project.

doc:name

Unique name for the exception strategy, if you wish. (Not required in Standalone.)

Attribute	Value
ref	Name of the global `catch-exception-strategy` in your project.
doc:name	Unique name for the exception strategy, if you wish. (Not required in Standalone.)

<catch-exception-strategy name="Catch_Exception_Strategy">
    <logger message="#[payload]" level="INFO" doc:name="Logger"/>
</catch-exception-strategy>

<flow name="Creation1Flow1" doc:name="Creation1Flow1">
    <http:inbound-endpoint exchange-pattern="request-response" host="localhost" port="8081" doc:name="HTTP"/>
    <cxf:jaxws-service doc:name="SOAP"/>
...
    <exception-strategy ref="Catch_Exception_Strategy" doc:name="Reference Exception Strategy"/>
    </flow>

You can append a Reference Exception Strategy to any number of flows in your Mule application and instruct them to refer to any of the global catch, rollback, or choice exception strategies you have created. You can direct any number of reference exception strategies to refer to the same global exception strategy.

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Catch Exception Strategy

When to Use

Studio Visual Editor

Studio XML Editor or Standalone

Configuring a Catch Exception Strategy

Studio Visual Editor

Studio XML Editor or Standalone

Creating a Global Catch Exception Strategy

Studio Visual Editor

Studio XML Editor or Standalone

Applying a Global Catch Exception Strategy to a Flow

Studio Visual Editor

Studio XML Editor or Standalone

See Also