Mule Errors | MuleSoft Documentation
# 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  
---|---|---  
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]`  
A type, used to characterize the problem and allow for routing within an error handler. | `#[error.errorType]`  
The underlying Java `Throwable` that resulted in the failure. | `#[error.cause]`  
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: `[]`
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:
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>
```

## See Also
  * On-Error Components
  * Logging and Debugging