Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.1)
  3. General Configurations
  4. Error Handling

  5. Mule Errors

Mule Errors

Standard Support for Mule 4.1 ended on November 2, 2020, and this version of Mule reached its End of Life on November 2, 2022, 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.

Mule execution failures result in a Mule Error. Each Mule Error has the following components:

Component Description Expression

Description

A description regarding the problem

#[error.description]

Type

A type, used to characterize the problem and allow routing within an error handler

#[error.errorType]

Cause

The underlying Java Throwable that resulted in the failure

#[error.cause]

Message

An optional Mule Message regarding the problem

#[error.errorMessage]

Child Errors

An optional collection of inner errors, used by elements like Scatter-Gather to provide aggregated route errors.

#[error.childErrors]

Each component in a Mule application declares the type of errors it throws so it’s easy for you to identify potential errors when designing a Mule flow.

For example, when an HTTP request fails with a 401 status code, the Mule Error looks like this:

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

Error Types

In the example above, the error type is HTTP:UNAUTHORIZED, not simply UNAUTHORIZED.
Error types consist of both a namespace and an identifier, allowing you to distinguish the types according to their domain. For example, there are HTTP:NOT_FOUND and FILE:NOT_FOUND error types.
While connectors define their namespace, core runtime errors have the implicit MULE one.
So MULE:EXPRESSION and EXPRESSION are interpreted as one.

Another important characteristic of error types is that they may have a parent type. For example, HTTP:UNAUTHORIZED has MULE:CLIENT_SECURITY as the parent, which, in turn, has MULE:SECURITY as the parent. This establishes error types as specifications of more global ones: an HTTP unauthorized error is a type of client security error, which is a type of a more broad security issue.

These hierarchies allow routing to be more general. For example, a handler for MULE:SECURITY catches HTTP unauthorized errors as well as OAuth errors.
Below you can see what the core runtime’s hierarchy looks like:

Error Hierarchy

All errors belong to one of these two main types: ANY or CRITICAL. All types under ANY are matched by its parent and can be handled, while error types under CRITICAL are so severe that cannot be handled and will only be logged.

Whenever there is no clear reason for the failure, a component can use the UNKNOWN type. This error needs to be handled through the ANY type, allowing you to define unclear errors in the future, without changing the existing behavior of the app.

When it comes to connectors, each connector defines its error type hierarchy considering the core runtime hierarchy, though CONNECTIVITY and RETRY_EXHAUSTED types are always present since they are common to all connectors.

Below is a full list of Error Types:

  • ANY: error type that matches all error types that may occur in a Flow and can be handled. This does not include errors that may occur on the source.

    • TRANSFORMATION: indicates an error occurred while transforming a value. This involves Mule Runtime internal transformations and not DataWeave transformations.

    • EXPRESSION: indicates an error occurred while evaluating an expression.

    • VALIDATION: indicates a validation error occurred.

      • DUPLICATE_MESSAGE: indicates a validation error regarding a message being processed twice. For example, using the Idempotent message validator.

    • REDELIVERY_EXHAUSTED: indicates that max attempts to reprocess a message from a source have been exhausted.

    • CONNECTIVITY: indicates that there was a problem establishing a connection. This could occur while using a connector, for example, an HTTP requester.

      • RETRY_EXHAUSTED: indicates that retries of a certain execution block have been exhausted. For example, for a given operation, or using Until Successful Scope.

    • ROUTING: indicates an error occurred while routing a message. For example, using the Round Robin router.

      • COMPOSITE_ROUTING: indicates that one or more errors occurred while routing a message. For example, using a Scatter Gather Router.

    • SECURITY: indicates a security error occurred, like invalid credentials being received or an expired token being used.

      • CLIENT_SECURITY: indicates an external entity (e.g., calling an external endpoint) produced a security error.

      • SERVER_SECURITY: indicates a security error enforced by the Mule Runtime.

    • STREAM_MAXIMUM_SIZE_EXCEEDED: indicates the maximum size allowed for a stream has been exceeded. For more insight, see Streaming in Mule Apps.

    • TIMEOUT: indicates timeout occurred while processing a message.

    • UNKNOWN: indicates an unknown or unexpected error occurred. This cannot be handled directly, only by handling ANY, to ensure backward compatibility in case more error types are added in future runtime versions.

  • SOURCE: indicates that an error occurred in the source of the flow. These errors cannot be handled.

    • SOURCE_ERROR_RESPONSE_GENERATE: indicates that an error occurred in the source of the flow generating the parameters of an error response. This error cannot be handled since the source has already executed the failing path.

    • SOURCE_ERROR_RESPONSE_SEND: indicates that an error occurred in the source of the flow sending an error response. This error cannot be handled since the source has already executed the failing path.

  • SOURCE_RESPONSE: indicates that an error occurred in the source of a flow while processing a successful response. These errors can only be propagated since the source has already executed the successful path. These errors cannot be handled.

    • SOURCE_RESPONSE_GENERATE: indicates an error occurred in the source of the flow while generating the parameters of a successful response.

    • SOURCE_RESPONSE_SEND: indicates an error occurred in the source of the flow while sending a successful response.

  • CRITICAL: indicates a severe error occurred. These errors cannot be handled.

    • OVERLOAD: indicates a problem of overloading occurred and the execution was rejected.

      • FLOW_BACK_PRESSURE: indicates a problem of overloading occurred at the source level. For example, using an HTTP listener as a source.

    • FATAL_JVM_ERROR: indicates that a fatal error occurred, such as stack overflow.

Custom Error Types

To use custom error types, you need to define them either when mapping or when raising the errors. These errors require a specific custom namespace to distinguish them from other existing types within an application. This means that in an application using HTTP and DB, those two namespaces cannot be used. You should define namespaces related to the particular Mule application name or context, and avoid using existing connector namespaces.

For example, a customer aggregation API could use the CUSTOMER namespace for it’s custom error types and an order processing API could use the ORDER namespace.

Error Mappings

In each operation of your flow, you can map the possible error types to a custom error type of your choosing. You can use these custom error types to differentiate exactly where an error occurred in your flow.

For example, if your flow has two HTTP Request operations that reach out to different REST services, a connectivity failure on either produces the same error. But by mapping each to different custom error types, you can differentiate the error handling of each operation failure and also quickly identify the source of the error in the Mule application logs.

In the example below, you can see how mappings allow granular error handling by defining two custom error types: APP:CUSTOMER_API and APP:ORDER_API.

Example XML Configuration for Mappings:

<flow name="retrieveMatchingOrders">
  <http:request config-ref="customersConfig" path="/customer">
    <error-mapping sourceType="CONNECTIVITY" targetType="APP:CUSTOMER_API"/>
  </http:request>
  <http:request config-ref="ordersConfig" path="/order">
    <error-mapping sourceType="CONNECTIVITY" targetType="APP:ORDER_API"/>
  </http:request>
  <error-handler>
    <on-error-continue type="APP:CUSTOMER_API">
      <logger message="#['Could not retrieve customer data.']"/>
    </on-error-continue>
    <on-error-continue type="APP:ORDER_API">
      <logger message="#['Could not retrieve customer order data.']"/>
    </on-error-continue>
  </error-handler>
</flow>

See Also