Error Handling in Mule 4


Error Handing in Mule 4 has been very much simplified as compared to MuleSoft 3. This tutorial explains the different ways to handler errors in Mule 4. These are based on actual learning and the documentation from MuleSoft documentation. You can refer to link for Error Handing in Mule 4


Types of Errors


There are broadly two ways to define the errors in Mulesoft as below.

  • Message Level Errors – Message level error occurs when mule message is involved. e.g. error occurred when calling a database or error occurred (http 401 unauthorized or 503 service unavailable etc.) while calling an external API
  • System Level Error – System level error occurs when there is no mule message involved. E.g. connectivity issue to a JMS provider, connectivity issue to a Database. You cannot handle system level errors.


Error Type in MuleSoft


Mule 4 has structured all the errors as per the error Types, which consists of namespace and an identifier separated by “:Therefore, it is easy to identify the type of error (e.g. HTTP:CONNECTIVITY, DB:CONNECTIVITY etc) and take the action accordingly.

Every Connector raises the Error with the Error type which include namespace and identifier. All error type in follows hierarchy below.


Error Hierarchy


You can override the error type with your custom error types also.  All errors should be handled and proper error message should be used to send the appropriate error response back to the consumer of the API.


Classification of errors


You should first segregate the errors, so that you can take appropriate action whenever the error occurs in the mule Flow. you can classify as in example below.

  • Business Errors
    • Data error
    • Validation error
  • Technical Errors
    • Connectivity errors
    • Dataweave expression related errors
  • APIkit Router Errors
  • Any Unhandled Errors


Raising and Handling errors


There are two aspects when you deal with errors in your flow. First is to Raise an error and another is to Handle the errors.

  • Raising an error


    • Automatic – Error is raised automatically by Mulesoft. e. g. if there is a connectivity error while calling an API or when the Dataweave expression breaks if you are trying to append null with some static string.
    • Manually – This is typically used to raise the business errors. Following are the ways which you can raise an error in the flow
      • Validation Module – You can refer to the link Validation Module for more details on it.
	<validation:is-true doc:name="customer age validation" doc:id="5bc8d1c3-b124-4a38-8d62-9a9c9047f06c" expression="#[payload.age > 30]" message='#["Age should be less than 30"]'>
			<error-mapping targetType="MULESY:BUSINESS_VALIDATION" />


Enter the corresponding business error in the “Message” (can also be complied dynamically as it allows expression) placeholder under “Error options” as below. The same error would be available in the error object using “error.detailedDescription”


Error Handling in Mule 4


Map the “Mule error type” with “custom error type”. Create your own Namespace and Identifier as an example below. This will help in handling error which we will discuss next.


Error Handling in Mule 4


This will raise the following error object. The error message can be retrieved by using “error.detailedDescription” expression.


Error Handling in Mule 4


      • Raise error Message processor

<raise-error doc:name="Raise error" doc:id="10cb8ea0-19bc-4753-9cd6-67f1eafd865e" type="MULESY:BUSINESS_VALIDATION" description='"Processing stopped as the age is less then 30"' />


Map the error type and error description (only static error message is allowed) accordingly



This will raise the following error object. The error message can be retrieved by using “error.detailedDescription” expression.


Error Handling in Mule 4


  • Handing the error

The error raised as explained above should be handled and a proper error response should be sent to the consumer. You can handle errors depending upon the error types you have mapped. There are following ways to handle the error in Mule 4.

    • Try scope

When you want to handle errors while executing a set of message processor, you can wrap those message processors in try scope. E.g. if you want to continue processing the collection even if the processing of one of the objects fails (as shown in the screen shot below)



if you want to handle any error raised in a sub flow.



    • On error continue

Use on error continue error handler, when you do not want to let the parent flow/sub flow know that error has occurred and want to continue the processing further.

E.g. if you are processing a collection in a for-each scope and do not want to stop processing if any error occurs in processing an object. Another example, if you are performing a business validation which is not that important to stop the processing but should send a notification to some application.



You can have the “Type” defined so that, the error handler will be executed only when the “error.errorType” matches with the one defined.

For advanced condition matching you can use the When attribute with dataweave expression enabled.

You can have multiple “on error continue” handler with different “Type” in each handler.

    • On error propagate

Use “on error propagate” error handler when you want to propagate the error to the calling parent flow or sub flow.

By default the errors are propagated to the parent flow even if you don’t have “on error propagate” error handler, however with error handler you can execute any message processor to take some action (creating a service now ticket) along with propagating the errors.



    • Error Handler

For all the errors which are not handled by flow error handlers, can be handled by Error handler scope.

This allows you to define a global error handling strategy in your project. it can contain any number of internal error handlers and it routes the error to the first one matching.


Best practices for Error handling


  • Handle all error at one place except for the activities in Async scope (Async scope executes the message processor inside it in another thread hence you will not be able to propagate error to parent thread). Propagate the exception from various flows/sub flows to the parent main flow or sub flow.


  • Use the custom error type to segregate the actions on error type. E.g. if there is any business validation failure in the flow, you would not want to inform your support to act. But you would like to inform the support in case there is connectivity issue with any third-party application.


  • Create a generic error message for your API response and use it in APIkit router Error Handlers. Make use of Mule correlation id to correlate between request and response.
"error": {
"type": "Data not found Exception",
"message": "No setup Found for this location",
"errorcode": 435,
"correlationid": "674iw67r4fsla43rdfssdf23",
"http-response": {
"status": 404,
"message": "Not Found"

"error": {
"type": "Internal_Server_Error",
"message": "Internal server error",
"errorcode": 435,
"correlationid": "674iw67r4fsla43rdfssdf23",
"http-response": {
"status": 500,
"message": "Internal server error"



  • Handling chain of errors.

You can have chain of errors in your error object. e.g A http requestor connector is inside until successful scope. If the http request fails due to connectivity issue, until successful scope will retry and throw another error with error type as “RETRY:EXHAUSTED

To check if the error occurred due to connectivity you can look for error.errorType.parentErrorType.identifier

you can go further to get the ultimate root error Error Type as. error.errorType.parentErrorType.parentErrorType.identifier



  • Map the custom error type as below for your organization. Here are some of the examples.


Type of Error Classification of Error Identifier Namespace Description
Business Data error {ORG} DATA_{business entity} e.g. MULESY:DATA_CUSTOMER, MULESY:DATA_ORDER
Business Data Validation {ORG} VALIDATION_{business_entity} Error raised while performing any business validation. E.g. if you want to validate if the age coming in the request is greater than 30


Technical Third party API Connectivity {THIRD_PARTY_API} {CONNECTIVITY} If you want to segregate between errors raised by some external API, you can map the errors in HTTP requestor connector.


Technical Database Connectivity {THIRD_PARTY_DB} {CONNECTIVITY} If you want to segregate between errors raised by some external API, you can map the errors in HTTP requestor connector. e.g.



We hope you liked the tutorial. please do let us know if you have any other way to handle errors in MuleSoft. Happy reading and learning!


Thank you for taking out time to read the above post. Hope you found it useful. In case of any questions, feel free to comment below. Also, if you are keen on knowing about a specific topic, happy to explore your recommendations as well.
For any latest updates or posts on our website, you can follow us on LinkedIn. Look forward to connecting with you there.

Share this:
Notify of
1 Comment
Newest Most Voted
Inline Feedbacks
View all comments
1 year ago

Thank you so much !