MuleSoft Error Handling Basics
Errors happen in every integration. A database goes offline. An external API returns an unexpected format. A network times out. Without error handling, your MuleSoft application crashes or silently loses data. Proper error handling makes your application resilient, informative, and production-ready.
What Happens When an Error Occurs
When a component inside a flow throws an error, MuleSoft immediately stops the normal flow execution. The remaining components in the flow do not run. Control passes to the error handler block at the bottom of the flow. If no error handler exists, MuleSoft uses a default error handler that returns a 500 Internal Server Error response.
Error Flow Interruption Diagram
Normal Execution:
[HTTP Listener] --> [Transform] --> [Database] --> [Logger] --> [Response]
Error Occurs at Database:
[HTTP Listener] --> [Transform] --> [Database]
|
(Connection refused error)
|
v
[Normal flow STOPS here]
|
v
[Error Handler runs instead]
[Logger: log the error]
[Set Payload: error JSON]
[Response: HTTP 500]
Error Types in MuleSoft
Every error in MuleSoft has an error type. The error type is a namespace and identifier separated by a colon. Knowing the error type lets you handle specific errors differently from others.
Common Error Types
Error Type | When It Occurs --------------------------|--------------------------------------------- HTTP:CONNECTIVITY | Cannot reach the external HTTP server HTTP:UNAUTHORIZED | HTTP 401 response received HTTP:NOT_FOUND | HTTP 404 response received HTTP:TIMEOUT | HTTP request timed out DB:CONNECTIVITY | Cannot connect to the database DB:QUERY_EXECUTION | SQL query failed FILE:NOT_FOUND | File does not exist MULE:EXPRESSION | DataWeave script has an error ANY | Matches any error type (catch-all)
On Error Propagate vs On Error Continue
The two most important error handler types have very different behaviors:
On Error Propagate
Use this when the error should be reported to the caller. After the error handler runs, MuleSoft sends the error back to whatever triggered the flow. If an HTTP client called the flow, it receives an error response. This is the correct behavior for APIs where the caller needs to know something went wrong.
On Error Continue
Use this when you want to handle the error gracefully and continue as if the flow succeeded. After the error handler runs, MuleSoft treats the flow as successful and uses whatever payload was set in the error handler as the response. Use this when you want to return a default value on failure instead of an error.
Propagate vs Continue Comparison
Scenario: Database is offline.
On Error PROPAGATE:
Error handler logs the error.
Error handler sets payload to {"error": "Database unavailable"}.
Flow sends HTTP 500 response to the caller.
Caller sees: HTTP 500 {"error": "Database unavailable"}
On Error CONTINUE:
Error handler logs the error.
Error handler sets payload to []. (empty list as default)
Flow sends HTTP 200 response to the caller.
Caller sees: HTTP 200 [] (empty result, no indication of failure)
Adding an Error Handler in Studio
Every flow in Anypoint Studio has an expandable error handler section at the bottom. Click the plus icon in the flow's error handler area. A menu appears with options including On Error Propagate and On Error Continue. After adding the error handler type, drag components into it just like a normal flow: Logger, Set Payload, HTTP Request to notify another system, and so on.
Error Handler Configuration in Canvas
+------------------------------------------------------------------+ | FLOW: createOrderFlow | | [HTTP Listener] --> [Validate] --> [DB Save] --> [Response] | | | | ERROR HANDLER | | +-----------------------------+ +---------------------------+ | | | On Error Propagate | | On Error Continue | | | | Type: DB:CONNECTIVITY | | Type: MULE:EXPRESSION | | | | | | | | | | [Logger: DB offline] | | [Logger: bad input] | | | | [Set Payload: 503 message] | | [Set Payload: defaults] | | | | [HTTP status: 503] | | | | | +-----------------------------+ +---------------------------+ | +------------------------------------------------------------------+
Global Error Handlers
A global error handler applies to all flows in the application that do not have their own error handler. You define it once and reference it by name. Use a global error handler for company-wide standards like always logging errors to a central system or always returning a consistent error response format.
Global Error Handler Setup
Global Error Handler (defined once in the XML):
Name: "globalErrorHandler"
On Error Propagate: ANY
[Logger: "#[error.description]"]
[Set Payload:
{ "errorCode": "#[error.errorType.identifier]",
"message": "#[error.description]",
"timestamp": "#[now()]" }]
[HTTP status: 500]
Flow 1: processOrderFlow
error-handler-ref = "globalErrorHandler" <-- uses global handler
Flow 2: syncCustomerFlow
error-handler-ref = "globalErrorHandler" <-- same global handler
Flow 3: paymentFlow
(has its own error handler for payment-specific errors)
Retry on Error
Some errors are temporary. A network blip causes a timeout, but the next attempt succeeds. MuleSoft's reconnection strategy lets you configure automatic retries for connector operations.
Reconnection Strategy Example
HTTP Request Connector Configuration:
Reconnection:
Reconnect until timeout:
Frequency: 2000 ms (retry every 2 seconds)
Blocking: true
Behavior:
Attempt 1 at 09:00:00.000 --> Connection failed
Wait 2 seconds
Attempt 2 at 09:00:02.000 --> Connection failed
Wait 2 seconds
Attempt 3 at 09:00:04.000 --> Connection succeeded --> Continue flow
Raising Errors Manually
Use the Raise Error component when your business logic detects a problem. For example, if an order amount is negative, you raise a custom error instead of proceeding with invalid data.
[Choice Router: is amount negative?]
Yes -->
[Raise Error:
Type: ORDER:INVALID_AMOUNT
Description: "Order amount cannot be negative"]
No -->
[Continue processing]
Error Handler:
On Error Propagate: ORDER:INVALID_AMOUNT
[Set Payload: {"error": "Invalid order amount"}]
[HTTP status: 400]
Best Practices for Error Handling
- Always add an error handler to every production flow. Never leave it empty.
- Log the full error description and error type in every error handler.
- Include a correlation ID in error responses so support teams can trace issues across logs.
- Use specific error types in handlers when different errors need different responses. Use
ANYas a final catch-all. - Never expose internal error details like stack traces or database table names to external API consumers. Log them internally and return a clean message to the caller.