Mule Errors

Mule execution failures result in an error. When a Mule app is running, both the Mule runtime engine and the module and connector operations configured in the app can throw errors that are represented by a Mule error object, which is associated with a Mule event. You can handle error objects with On-Error components and find information about them in the logs.

Mule errors are grouped into error types that follow a hierarchical order and use a naming convention that helps you identify the source of the error and handle the error at the level you choose. You can also create custom error types that you map to these errors. The mappings can help you further differentiate and group errors that you need to handle in your app.

To inspect and use values of Mule errors in your error handling configurations, you can also use selector expressions.

Mule errors include expression (EXPRESSION) and stream-related errors (STREAM_MAXIMUM_SIZE_EXCEEDED), while the operations can throw many different types of errors. Examples include HTTP:NOT_FOUND (a 404 error) and HTTP:CONNECTIVITY errors from the HTTP listener in the HTTP connector. DB:BAD_SYNTAX and DB:QUERY_EXPRESSION are errors that the Select operation in the Database connector can throw.

The reference documentation for modules and connectors (for example, the HTTP Connector and Database Connector references) lists Mule errors.

Selector Expressions for Mule Errors

Mule errors are complex data types with several fields, such as a description and type. When logging and handling Mule errors, can select the values from any number of the error fields.

Field Description Selector Expression

Field	Description	Selector Expression
Description	A description of the problem.	`#[error.description]`
Detailed Description	A description of the problem, which can be the same or more extensive than the description.	`#[error.detailedDescription]`
Type	A type, used to characterize the problem and allow for routing within an error handler.	`#[error.errorType]`
Cause	The underlying Java `Throwable` that resulted in the failure.	`#[error.cause]`
Message	An optional Mule message about 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]`

Description

A description of the problem.

#[error.description]

Detailed Description

A description of the problem, which can be the same or more extensive than the description.

#[error.detailedDescription]

Type

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

#[error.errorType]

Cause

The underlying Java Throwable that resulted in the failure.

#[error.cause]

Message

An optional Mule message about 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]

In most cases, the error.cause selector returns a Throwable instance that is part of the Mule API. Do not access the error’s internal structure to define error handling logic. The other selectors expose all the necessary information to handle errors. Also, serializing the error.cause might result in redundant information.

HTTP Request Error Example

For example, when an HTTP request fails with an HTTP:NOT_FOUND error (for a 404 status code), the values for each part of the Error Message are:

#[error.description] returns:

HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/mybadrequest' failed: not found (404).

#[error.detailedDescription] returns HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/mybadrequest' failed: not found (404).
#[error.errorType] returns HTTP:NOT_FOUND
#[error.cause] returns org.mule.extension.http.api.request.validator.ResponseValidatorTypedException. If you print the return instance of ResponseValidatorTypedException, Mule prints the result of toString. When the error has an associated known HTTP status code (such as 404), the string representation of the ResponseValidatorTypedException instance is a human-readable description of the error.

#[error.errorMessage] returns:

org.mule.runtime.core.internal.message.DefaultMessageBuilder$MessageImplementation
{
  payload=org.mule.runtime.core.internal.streaming.bytes.ManagedCursorStreamProvider@223d8f75
  mediaType=application/json; charset=UTF-8
  attributes=org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=404
   Reason Phrase=Not Found
   Headers=[
      date=Sat, 03 Aug 2019 04:28:29 GMT
      content-type=application/json; charset=utf-8
      content-length=2
      connection=keep-alive
      set-cookie=__cfduid=de19ed0b495b5b58e74fa0ee31a700d651564806509; expires=Sun, 02-Aug-20 04:28:29 GMT; path=/; domain=.typicode.com; HttpOnly
      x-powered-by=Express
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=public, max-age=14400
      pragma=no-cache
      expires=Sat, 03 Aug 2019 08:28:29 GMT
      x-content-type-options=nosniff
      etag=W/"2-vyGp6PvFo4RvsFtPoIWeCReyIC8"
      via=1.1 vegur
      cf-cache-status=HIT
      age=96
      server=cloudflare
      cf-ray=50058b8add0a92fe-SJC
   ]
}
  attributesMediaType=*/*
}

The errorMessage element becomes available when a connector or component exposes the message that it has interpreted as an error. For example, when an HTTP request receives a status code that Mule treats as an error, the process fails and also populates the errorMessage with information about the error. You can then gain access to error message attributes (metadata) and to the payload itself with #[error.errorMessage.payload] for the payload and #[error.errorMessage.attributes] for the metadata. In the case of an HTTP request that returns an error, you can then use #[error.errorMessage.attributes.statusCode] to select the value of the status code (such as 404). To see message attributes in Studio, see DataSense.

#[error.childErrors] returns: []

Mule Error Types

Mule errors have a namespace (such as HTTP: and FILE:) and identifier (such as NOT_FOUND), and they belong to a hierarchy of error types.

The naming convention enables you to distinguish errors according to their domain. For example, instead of throwing NOT_FOUND, the HTTP connector can throw HTTP:NOT_FOUND, and the File connector can throw FILE:NOT_FOUND errors.

Unlike connectors, Mule runtime errors have an implicit MULE namespace, so MULE:EXPRESSION and EXPRESSION are interpreted the same way.

Error types can have a parent type. For example, the parent of HTTP:UNAUTHORIZED is MULE:CLIENT_SECURITY, and the parent of MULE:CLIENT_SECURITY is MULE:SECURITY. This hierarchy implies that each error type is a specification of more global error type. For example, an HTTP:UNAUTHORIZED error type is a type of client security error (MULE:CLIENT_SECURITY), which is a type of a more broad security issue (MULE:SECURITY).

The hierarchies enable you to route errors in a general or more specific way. For example, an error handler for MULE:SECURITY catches HTTP:UNAUTHORIZED errors and OAuth errors. The follow figure shows the core runtime hierarchy:

A hierarchy of error types showing categories including ANY and CRITICAL

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

Whenever there is no clear reason for a failure, a component can use the UNKNOWN type. You handle this error through the ANY type to define unclear errors, without changing the existing behavior of the app.

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

Error Types:

ANY: error type that matches all error types that occur in a Flow and can be handled. This type does not include errors that 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 a DataWeave 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.
    
    NOT_PERMITTED: indicates a security restriction enforced by a filter. For example, using the Authorization Filter of the Mule Spring Module.
- 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 an app that uses HTTP and Database connector operations cannot use the HTTP and DB namespaces for custom error types.

You need to define namespaces that are related to the particular Mule app name or context and avoid using existing connector namespaces. For example, a customer aggregation API might use the CUSTOMER namespace for its custom error types, and an order-processing API might 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 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. By mapping each error to different custom error types, you can differentiate the error handling of each operation failure and quickly identify the source of the error in the Mule app logs.

In the following example, 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>