MuleSoft Error Handling Techniques with Examples

In this article we will learn Error Handling techniques in MuleSoft message flow along with working examples. Error Handling is core part of MuleSoft. In exams you may face 8-10 complex questions on Error Handling. When, I sat down to take the exam. It was harder than I expected. Sure, I may have struggled with a couple things, but overall I did well. The first thing that I realized is that when we are dealing with mule 4 error handling, don’t be panic, try to understand the core concept, which I am explaining in this article. We will discuss following topics in details with the help of examples:

Type of Errors in Mule 4

There are two types of errors in Mule 4.

System errors

System errors are errors that occur outside of Mule flows when no Mule events are involved. These are usually issues with during application start-up, deployment or mal-formed code or other external system fails such errors.
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.

Messaging errors

Messaging errors that happen within a flow when there is some kind of processing issue. These types of errors create Error Objects which (in most cases) can be handled. Let’s focus on Messaging Error.

What is an Error Object

Objects that are created when a Messaging Error occurs

Structure of an Error Object in Mule 4

Structure of an Error Object, when a message error occurs would be looked like as below.

Error handling scopes in Mule 4

There are two error handling scopes in Mule 4

On Error Propagate

• Executes but propagates the error to the next level up, breaking the user’s execution.
• If a transaction is being handled, it’s rolled back.

On Error Continue

• Executes and uses the result of the execution, as the result of its user, as if the owner had actually completed the execution successfully.
• If a transaction is being handled, it would be committed as well.

<on-error-propagate name="sharedPropagateHandler">
  <logger message="An unhandled error has occurred."/>
</on-error-propagate>

<on-error-continue type="EXPRESSION" name="sharedContinueHandler">
  <logger message="An expression failed to evaluate."/>
</on-error-continue>

<error-handler name="reusingHandlers">
  <on-error ref="sharedContinueHandler"/>
  <on-error-continue type="ROUTING">
    <logger message="An expression failed to evaluate."/>
  </on-error-continue>
  <on-error ref="sharedPropagateHandler"/>
</error-handler>

What is difference between On Error Propagate and On Error Continue?

Just to remember this – its core trick to remember. In following example we will differentiate On Error Propagate and On Error Continue scopes step by step for better understanding. Here we will use color coding (RED, GREEN) for identifying the input and output.

Note: Red means there’s a Mule Error Object is being passed to message flow. Green means a normal Mule message is being passed to message flow.

On Error Propagate Example : RED in RED out

In this example we are using an On Error Propagate scope.

Note: RED in RED out – Even though a payload is set in the On Error Propagate scope, because the scope is RED out, the original error message that was created is what is returned.

On Error Continue: RED in GREEN out

In this example we are using an On Error Continue scope.

Note: RED in GREEN out. Because this is an On Error Continue, GREEN out, the payload that is set in the error handler is returned and no error is passed back.

Mule Error Handling – On Error Propagate and On Error Continue Scope Example

Let’s start with a simple flow with a few simple components

• An HTTP Listener that initiates the flow
• A Set Payload processor that sets the payload to “Success – Started Flow”
• A Validator processor that checks to see if the current payload is a number
  • This is the part where an error will get created as the payload is a string (“Success – Started Flow”) and not a number
• A Set Payload processor that sets the payload to “Success – Finished Flow”

Mule Error Handling – On Error Propagate Scope

Let’s walkthrough step by step.

What’s happening here:

• Step 1: Payload is successfully set to “Success – Started Flow“
• Step 2: The Is Number validator creates an Error Object because the payload isn’t an integer
  • Flow execution stops
  • #[error.description] = “payload is not a valid INTEGER value“
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3: The On Error Propagate error Handler handles the error
  • The payload is set to “Error – Main Flow”
• Step 4: “payload is not a valid INTEGER value” is the error message returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 500

Mule Error Handling – On Error Continue Scope

Let’s walkthrough step by step.

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • Flow execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3: The On Error Continue scope handles the error
  • The payload is set to “Error – Main Flow”
• Step 4 : “Error – Main Flow” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 200

Error Handling Strategies in Mule 4

There are two types of Error Handling Strategies for implementing error handler in Mule 4.

Application level error handling
Flow level error handling

Application level Error Handling

In Mule 4 (MuleSoft) application we can handle or implement error handling in two ways and both the error handlers are reside outside the of the actual Mule Flow.

Default Error Handler
Global Error Handler

Default Error Handler

• The Mule Default Error Handler is included with every single Mule application.
• Simply, it is On Error Propagate without any processors (remember: RED in, RED out).

Note: The Mule Default Error Handler is that you cannot configure it. It use to call by default if there there in any Error Handler defined.

Global Error Handler

• The Global Error Handler can be configured to process errors and do what you want with them, therefore you can put an On-Error Propagate or an On Error Continue scope (or both, if you want to handle specific errors) in the Global Error handler.

How Mule Default Error Handler and Global Error Handler work?

Let’s see how these two work. We’ll continue using the same example as earlier in the simple examples section, except this time we won’t define any kind of error handler:

Mule Default Error Handler Example

What is expected to happen here is that an error thrown by the “Is number” validator will be caught and propagated by the Mule Default Error Handler:

Note: As I already mentioned the Mule Default Error Handler is not configurable and therefore is not visually depicted in the flow.

What is happening here, lets walkthrough step by step:

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • Flow execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3 : Because no error handler is defined, the Mule default error handler handles the error
• Step 4 : “payload is not a valid INTEGER value” is the error message returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 500

Global Error Handler

Now, let’s see how this process differs in processing if we use a Global Error Handler instead of the Mule Default Error Handler.

What is happening here, lets walkthrough step by step:

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • Flow execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3 : The Global Error Handler handles the error
  • The on error continue scope catches the error inside the global error handler
  • The payload is set to “Error – Global Error Handler”
• Step 4 : “Error – Global Error Handler” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 200

Note: Suppose we use On Error Propagate in above flow at Step 3, then it will work as Default Error Handler and will return HTTP Status Code: 500.

Flow level Error Handling

In this section we will learn how to handle error on Flow Level with the help of examples step by step.

What happens when the errors occure in another flow (i.e. a sub flow or child flow)?

We will use a very similar example to that above, except this example will have the Is Number validator in a child flow referenced by a Flow Reference processor from the parent flow as below

This is where things start to get a little more complex, but just remember your basics when it comes to error handling:

On Error Propagate: RED in RED out
On Error Continue: RED in GREEN out

Let’s evaluate step by step:

Sub-Flow: On Error Continue

In example (shown above) where the error will happen in the child flow and the error will be caught by an On Error Continue scope in the child flow:

• Step 1 : Payload is successfully set to “Success – Started Main Flow”
• Step 2 : The Flow Reference calls the child flow
• Step 3 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • Child Flow execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 4 : The On Error Continue handles the error
  • The payload is set to “Error – Sub Flow”
• Step 5 : “Error – Sub Flow” is returned to the main flow as if the child flow was a success
  • The Set Payload is executed
  • The payload is reset to “Success – Finished Main Flow”
• Step 6 : “Success – Main Flow” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 200

Sub-Flow: On Error Propagate

In the below example, we are using an On Error Propagate (RED in, RED out) to handle the error in the child flow. We will see a bit different:

Let’s evaluate step by step:

• Step 1 : Payload is successfully set to “Success – Started Main Flow”
• Step 2 : The Flow Reference calls the child flow
• Step 3 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • Child Flow execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 4 : The On Error Propagate handles the error
  • The payload is set to “Error – Sub Flow”
• Step 5 : “Error – Sub Flow” is returned to the main flow in the payload as if the child flow was a failure
  • The Flow Reference fails due to the failure from the childFlow
  • Main flow execution stops
  • Because there is no flow error handler for the main flow, the default behavior of a flow is to propagate the error
• Step 6 : “payload is not a valid INTEGER value” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 500

Processor level error handling in Mule 4

A try scope is used if we want to attempt to perform an action and catch the error and attempt to handle the error before failing an entire flow.

Try Scope: On Error Continue

Let’s evaluate Try Scope step by step.

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • Try scope execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3 : The Try Scope’s On Error Continue handles the error
  • The payload is set to “Error – Try Scope”
• Step 4 : The mainFlow execution continues
  • The payload is set to “Success – Finished Flow”
• Step 5 : “Success – Finished Flow” is returned to the requestor
  • HTTP Status Code: 200

Try Scope: On Error Propagate

Let’s evaluate Try Scope On Error Propagate step by step.

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • The Try Scope execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3 : The Try Scope’s On Error Propagate handles the error
  • The payload is set to “Error – Try Scope”
  • Because there is no flow error handler for the main flow, the default behavior of a flow is to propagate the error
• Step 4 : “payload is not a valid INTEGER value” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 500

Note : As if the processor level of error handling is not enough, MuleSoft allows you to go one level down to handle error. We will discuss in Handling specific error messages section.

Handling Specific Error messages in Mule 4

• It is very useful if you wish to handle specific errors in specific ways.
• For example, suppose we are trying to insert a record into a database, we would want to handle a duplicate record error differently we can handle using Specific Error message technique.

Note: Every error has a type, and every error type is comprised of two separate pieces: a namespace and an identifier.

HTTP:UNAUTHORIZED
HTTP:CONNECTIVITY
VALIDATION:INVALID_BOOLEAN

• The second piece to understand is that every error type has a parent.

• When we use an error handling scope (either On Error Propagate or On Error Continue) into a flow, it is set up to catch errors of type ANY (the parent of all error types) by default.

• If we wish to change this and handle specific errors, we have to define the type of errors to handle as below.

Example 1 : Handling specific error messages

In this example, the “is number” validator will fail throwing a VALIDATION:INVALID_NUMER error type which will be caught by the second error scope and therefore handled.

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • The Try Scope execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER
• Step 3 : The On Error Continue shape that handles the error
  • This is the first error scope that matches the type of “VALIDATION: INVALID_NUMBER”
  • The payload is set to “Error – Invalid Number”
• Step 4 : “Error = Invalid Number” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 200

Note: The error was not caught in the first error scope because the error type is VALIDATION:INVALID_NUMBER and the first error scope is looking for an error of type STREAM_MAXIMUM_SIZE_EXCEEDED and therefore the types didn’t match, so the error went to the next try scope in the code where the error type matched the expected error type.

Example 2 : Handling specific error messages

In this example we will discuss, suppose we specify the specific error types we want to handle, but the error that is thrown isn’t one that we specified? What will happen to the flow? Will Global Error Handler come to picture?

• Step 1 : Payload is successfully set to “Success – Started Flow”
• Step 2 : The Is Number validator creates an Error Object because the payload isn’t an integer
  • The mainFlow execution stops
  • #[error.description] = “payload is not a valid INTEGER value”
  • #[error.errorType] = VALIDATION:INVALID_NUMBER

Note: The error type of VALIDATION:INVALID_NUMBER is not one of the error types defined in the error scopes defined. Because no error scopes match the given error type, the default behavior of a flow is to propagate the error.

• Note – The global error handler isn’t the scope to handle this error
• “payload is not a valid INTEGER value” is returned to the requestor in the body of the HTTP request
  • HTTP Status Code: 500

Remember, if the error doesn’t match anything, it is handled by the Mule Default Error Handler.

Order of Error Handling, When an error occurs in Mule 4

When an error occurs it is handled in the following order:

• Processor level
• Flow level
• Application level

Keep learning. Have a great Day 🙂