Contact Us 1-800-596-4880

Raise Error Component

This version of Mule reached its End of Life on May 2, 2023, when Extended Support ended.

Deployments of new applications to CloudHub that use this version of Mule are no longer allowed. Only in-place updates to applications are permitted.

MuleSoft recommends that you upgrade to the latest version of Mule 4 that is in Standard Support so that your applications run with the latest fixes and security enhancements.

This core component generates a Mule error, as if a failure had occurred, which allows you to customize its description and type.

Use this component to only raise:

  • Core runtime errors, such as MULE:SECURITY, MULE:CONNECTIVITY, etc.

  • Custom error types.

You cannot raise an error from another connector or module like FILE:FILE_NOT_FOUND, JSON:INVALID_SCHEMA. You cannot use a connector’s existing namespace.

Raise Error Configuration

Field Value Description Example

Description

String or DataWeave expression

Specifies the error description.

description="Error description message."

Type

String

Specifies the type of the error.

type="CUSTOM:CUSTOM_ERROR"

Raise Core Runtime Error Types

For core runtime error types, you must use the implicit namespace and identifier, you can only customize the error’s description message. For example:

<raise-error type="MULE:CONNECTIVITY" description="Error description message"/>

Raise Custom Error Types

For custom error types, declare a new namespace. The namespace of an error type should help you identify the origin of an error. For example:

<raise-error type="ORDER:INVALID_DATA" description="Email is invalid. Cannot complete transaction"/>

You cannot use existing namespaces from connectors or modules, since these have their defined namespaces. Once you declare a custom namespace by using it in a raise-error, you can use it in other raise-error components and custom types.

Examples

The following example of a driving lessons platform checks that the user is over 16 years old to drive. The flow raises a PRECONDITIONS:INCORRECT_AGE error when the user enters an age lower than 16 years.

  • The Choice router components adds conditional processing to the flow.

  • If the age parameter sent in the request is lower than 16 http://localhost:8081/test?age=15, the Raise Error component raises the error type PRECONDITIONS:INCORRECT_AGE and description Minimum age of 16 required to drive.

  • Then, an On-Error Continue component matches the type of the error PRECONDITIONS:INCORRECT_AGE and executes the Logger component inside its scope. The Logger component logs the error message Minimum age of 16 required to drive.

  • If the age parameter is greater than 16 in the request http://localhost:8081/test?age=17, a Logger component returns the default message User age above 16 years. Allowed to drive.

  • If no age parameter is passed in the request http://localhost:8081/test the choice component will automatically raise a MULE:EXPRESSION error when trying to evaluate the expression #[message.attributes.queryParams.age < 16] because no age parameter was provided in the request, so its value is null.

  • Then, an On-Error Continue component matches the type of the error MULE:EXPRESSION and executes the Logger component inside its scope. The Logger component returns the message The parameter age is missing or invalid.

XML Configuration of the Flow:

<http:listener-config name="HTTP_Listener_config">
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<flow name="raise-error-example-flow">
  <http:listener config-ref="HTTP_Listener_config" path="/test"/>
  <choice>
    <when expression="#[message.attributes.queryParams.age &lt; 16]">
      <raise-error type="PRECONDITIONS:INCORRECT_AGE" description="Minimum age of 16 required to drive" />
    </when>
    <otherwise >
      <logger level="INFO" message="User age above 16 years. Allowed to drive"/>
    </otherwise>
  </choice>
  <error-handler >
    <on-error-continue enableNotifications="true" logException="true" type="PRECONDITIONS:INCORRECT_AGE">
      <logger level="INFO" message="Minimum age to drive is 16 years old"/>
    </on-error-continue>
    <on-error-continue enableNotifications="true" logException="true"  type="MULE:EXPRESSION">
      <logger level="INFO" message="The parameter age is missing or invalid"/>
    </on-error-continue>
  </error-handler>
</flow>

Consider an API that returns an account balance when making a request to https://unsecurebank.com/balance.
The following example, makes a request to this API and stores the value in the balance variable, then it compares it with payload.amount to determine if the operation is possible.
The Choice router produces an ACCOUNT:INSUFFICIENT_FUNDS error when a transfer amount surpasses the available balance, preventing the transfer from taking place. Additionally, it generates a dynamic description by providing an expression with failure details.

XML Configuration of the Flow:

<flow name="raise-error-example-flow">
  <http:request url="https://unsecurebank.com/balance" target="balance"/>
  <choice>
    <when expression="#[payload.amount > vars.balance]">
      <raise-error type="ACCOUNT:INSUFFICIENT_FUNDS" description="#['Cannot transfer $(payload.amount) since only $(vars.balance) are available.']"/>
    </when>
  </choice>
  <http:request url="https://unsecurebank.com/transfer"/>
</flow>