MuleSoft - Mule Error Handling


The new Mule error handling is one of the biggest and major changes done in Mule 4. The new error handing may seem complex, but it is better and more efficient. In this chapter, we are going to discuss about components of Mule error, Error types, categories of Mule error and components for handling Mule errors.

Components of Mule Error

Mule error is the result of Mule exception failure has the following components −


It is an important component of Mule error which will give description about the problem. Its expression is as follows −



The Type component of Mule error is used to characterize the problem. It also allows routing within an error handler. Its expression is as follows −



The Cause component of Mule error gives the underlying java throwable that causes the failure. Its expression is as follows −



The Message component of Mule error shows an optional message regarding the error. Its expression is as follows −


Child Errors

The Child Errors component of Mule error gives an optional collection of inner errors. These inner errors are mainly used by elements like Scatter-Gather to provide aggregated route errors. Its expression is as follows −



In case of failure of HTTP request with a 401 status code, the Mule Errors are as follows −

Description: HTTP GET on resource ‘http://localhost:8181/TestApp’ 
failed: unauthorized (401)
Cause: a ResponseValidatorTypedException instance
Error Message: { "message" : "Could not authorize the user." }
Sr.NO Error Type and Description


This Error Type indicates an error occurred while transforming a value. The transformation is Mule Runtime internal transformation and not the DataWeave transformations.



This kind of Error Type indicates an error occurred while evaluating an expression.



This kind of Error Type indicates a validation error occurred.



A kind of validation error which occurs when a message being processed twice.



This kind of Error Type occurs when maximum attempts to reprocess a message from a source has been exhausted.



This Error Type indicates a problem while establishing a connection.



This Error Type indicates an error occurred while routing a message.



This Error Type indicates a security error occurred. For example, invalid credentials received.



This Error Type occurs when the maximum size allowed for a stream exhausted.



It indicates the timeout while processing a message.



This Error Type indicates an unexpected error occurred.



It represents the occurrence of an error in the source of the flow.



It represents the occurrence of an error in the source of the flow while processing a successful response.

In the above example, you can see the message component of mule error.

Error Types

Let us understand the Error Types with the help of its characteristics −

  • The first characteristics of Mule Error Types is that it consists of both, a namespace and an identifier. This allows us to distinguish the types according to their domain. In the above example, the Error Type is HTTP: UNAUTHORIZED.

  • The second and important characteristic is that the Error Type may have a parent type. For example, the Error Type HTTP: UNAUTHORIZED has MULE:CLIENT_SECURITY as the parent which in turn also has a parent named MULE:SECURITY. This characteristic establishes the Error Type as specification of more global item.

Kinds of Error Types

Following are the categories under which all the errors fall −


The errors under this category are the errors that may occur in a Flow. They are not so severe and can be handled easily.


The errors under this category are the severe errors that cannot be handled. Following is the list of Error Types under this category −

Sr.NO Error Type and Description


This Error Type indicates an error occurred due to problem of overloading. In this case, the execution will be rejected.



This kind of Error Type indicates the occurrence of a fatal error. For example, stack overflow.

CUSTOM Error Type

The CUSTOM Error Types are the errors that are defined by us. They can be defined when mapping or when raising the errors. We must give a specific custom namespace to these Error Types for distinguishing them from the other existing Error Types within Mule application. For example, in Mule application using HTTP, we cannot use HTTP as the custom error type.

Categories of Mule Error

In broad sense, the errors in Mule can be divided into two categories namely, Messaging Errors and System Errors.

Messaging Error

This category of Mule error is related to the Mule flow. Whenever a problem occurs within a Mule flow, Mule throws a messaging error. We can set up On Error component inside the error handler component to handle these Mule errors.

System Error

System error indicates an exception occurring at the system level. If there is no Mule event, the system error is handled by a system error handler. The following kind of exceptions handle by a system error handler −

  • Exception that occurs during an application start-up.
  • Exception that occurs when a connection to an external system fails.

In case a system error occurs, Mule sends an error notification to the registered listeners. It also logs the error. On the other hand, Mule executes a reconnection strategy if the error was caused by a connection failure.

Handling Mule Errors

Mule has following two Error Handlers for handling the errors −

On-Error Error Handlers

The first Mule error handler is On-Error component, that defines the types of errors they can handle. As discussed earlier, we can configure On-Error components inside the scope-like Error Handler component. Each Mule flow contain only one error handler, but this error handler can contain as many On-Error scope as we needed. The steps for handling the Mule error inside the flow, with the help of On-Error component, are as follows −

  • First, whenever a Mule flow raises an error, the normal flow execution stops.

  • Next, the process will be transferred to the Error Handler Component that already have On Error component to match the error types and expressions.

  • At last, the Error Handler component routes the error to the first On Error scope that matches the error.

Handling Messaging

Following are the two types of On-Error components supported by Mule −

On-Error Propagate

On-Error Propagate component executes but propagates the error to the next level and breaks the owner’s execution. The transaction will be rolled back if it is handled by On Error Propagate component.

On-Error Continue

Like On-Error Propagate component, On-Error Continue component also executes the transaction. The only condition is, if the owner had completed the execution successfully then this component will use the result of the execution as the result of its owner. The transaction will be committed if it is handled by On-Error Continue component.

Try Scope Component

Try Scope is one of many new features available in Mule 4. It works similar to try block of JAVA in which we used to enclose the code having the possibility of being an exception, so that it can be handled without breaking the whole code.

We can wrap one or more Mule event processors in Try Scope and thereafter, try scope will catch and handle any exception thrown by these event processors. The main working of try scope revolves around its own error handling strategy which supports error handling on its inner component instead of whole flow. That is why we do not need to extract the flow into a separate flow.


Following is an example of the use of try scope −

Try Scope

Configuring try scope for handling transactions

As we know, a transaction is a series of actions that should never be executed partially. All the operations within the scope of a transaction are executed in the same thread and if an error occurs, it should lead to a rollback or a commit. We can configure the try scope, in the following manner, so that it treats child operations as a transaction.

Configuring Try Scope
  • INDIFFERENT [Default] − If we choose this configuration on try block, then the child actions will not be treated as a transaction. In this case, error causes neither rollback nor commits.

  • ALWAYS_BEGIN − It indicates that a new transaction will be started every time the scope is executed.

  • BEGIN_OR_JOIN − It indicates that if the current processing of the flow has already started a transaction, join it. Otherwise, start a new one.