[[ErrorHandler-ErrorHandler]]
Error Handler
~~~~~~~~~~~~~

Camel supports pluggable
http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/ErrorHandler.html[ErrorHandler]
strategies to deal with errors processing an
link:event-driven-consumer.html[Event Driven Consumer]. An alternative
is to specify the error handling directly in the link:dsl.html[DSL]
using the link:exception-clause.html[Exception Clause].

For introduction and background material see
link:error-handling-in-camel.html[Error handling in Camel].

*Exception Clause*

Using link:error-handler.html[Error Handler] combined with
link:exception-clause.html[Exception Clause] is a very powerful
combination. We encourage end-users to use this combination in your
error handling strategies. See samples and
link:exception-clause.html[Exception Clause].

*Using try ... catch ... finally*

Related to error handling is the link:try-catch-finally.html[Try Catch
Finally] as DSL you can use directly in your route. Its basically a
mimic of the regular try catch finally in the Java language but with
more power.

The current implementations Camel provides out of the box are:

[[ErrorHandler-Nontransacted]]
Non transacted
++++++++++++++

* link:defaulterrorhandler.html[DefaultErrorHandler] is the default
error handler in Camel. This error handler does not support a dead
letter queue, it will propagate exceptions back to the caller, as if
there where no error handler at all. It has a limited set of features.
* link:dead-letter-channel.html[Dead Letter Channel] which supports
attempting to redeliver the message exchange a number of times before
sending it to a dead letter endpoint
* LoggingErrorHandler for just catching and logging exceptions
* NoErrorHandler for no error handling

[[ErrorHandler-Transacted]]
Transacted
++++++++++

* link:transactionerrorhandler.html[TransactionErrorHandler] is the
default error handler in Camel for transacted routes. See the
link:transactional-client.html[Transactional Client] EIP pattern.

These error handlers can be applied in the link:dsl.html[DSL] to an
entire set of rules or a specific routing rule as we show in the next
examples. Error handling rules are inherited on each routing rule within
a single link:routebuilder.html[RouteBuilder]

[[ErrorHandler-ShortSummaryoftheprovidedErrorHandlers]]
Short Summary of the provided Error Handlers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[[ErrorHandler-DefaultErrorHandlerhttps://cwiki.apache.org/confluence/pages/viewpage.action?pageId=113880]]
link:defaulterrorhandler.html[DefaultErrorHandler]
++++++++++++++++++++++++++++++++++++++++++++++++++

The link:defaulterrorhandler.html[DefaultErrorHandler] is the default
error handler in Camel. Unlike link:dead-letter-channel.html[Dead Letter
Channel] it does not have any dead letter queue, and do *not* handle
exceptions by default.

[[ErrorHandler-DeadLetterChannelhttps://cwiki.apache.org/confluence/pages/viewpage.action?pageId=49482]]
link:dead-letter-channel.html[Dead Letter Channel]
++++++++++++++++++++++++++++++++++++++++++++++++++

The link:dead-letter-channel.html[Dead Letter Channel] will redeliver at
most 6 times using 1 second delay, and if the exchange failed it will be
logged at ERROR level.

You can configure the default dead letter endpoint to use:

or in Spring DSL

[source,xml]
-----------------------------------------------------------------------------------------------------
<bean id="deadLetterErrorHandler" class="org.apache.camel.builder.DeadLetterChannelBuilder">
  <property name="deadLetterUri" value="log:dead"/>
</bean>

<camelContext errorHandlerRef="deadLetterErrorHandler" xmlns="http://camel.apache.org/schema/spring">
  ...
</camelContext>
-----------------------------------------------------------------------------------------------------

or also from *Camel 2.3.0 onwards*

[source,xml]
--------------------------------------------------------------------------------------------------
<camel:errorHandler id="deadLetterErrorHandler" type="DeadLetterChannel" deadLetterUri="log:dead">

<camel:camelContext errorHandlerRef="deadLetterErrorHandler">
  ...
</camel:camelContext>
--------------------------------------------------------------------------------------------------

[[ErrorHandler-LoggingErrorHandler]]
Logging Error Handler
+++++++++++++++++++++

The logging error handler will log (by default at ERROR level) whenever
an uncaught exception is thrown. The logging category, logger and level
may all be defined in the builder.

[source,java]
----------------------------------------------------------------------------
errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.INFO));
----------------------------------------------------------------------------

or in Spring DSL

[source,xml]
--------------------------------------------------------------------------------------------------
<bean id="loggingErrorHandler" class="org.apache.camel.builder.LoggingErrorHandler">
  <property name="logName" value="mylogger.name"/>
  <property name="level" value="DEBUG"/>
</bean>

<camelContext errorHandlerRef="loggingErrorHandler" xmlns="http://camel.apache.org/schema/spring">
  ...
</camelContext>
--------------------------------------------------------------------------------------------------

or also from *Camel 2.3.0 onwards*

[source,xml]
---------------------------------------------------------------------------------------------------------------
<camel:errorHandler id="loggingErrorHandler" type="LoggingErrorHandler" logName="mylogger.name" level="DEBUG"/>

<camel:camelContext errorHandlerRef="loggingErrorHandler">
  ...
</camel:camelContext>
---------------------------------------------------------------------------------------------------------------

This would create an error handler which logs exceptions using the
category mylogger.name and uses the level INFO for all log messages
created.

[source,java]
---------------------------------------------------------------------------------------------------------
from("seda:a").errorHandler(loggingErrorHandler("mylogger.name").level(LoggingLevel.DEBUG)).to("seda:b");
---------------------------------------------------------------------------------------------------------

Loggers may also be defined for specific routes.

[[ErrorHandler-NoErrorHandler]]
No Error Handler
++++++++++++++++

The no error handler is to be used for disabling error handling.

[source,java]
-------------------------------
errorHandler(noErrorHandler());
-------------------------------

or in Spring DSL

[source,xml]
---------------------------------------------------------------------------------------------
<bean id="noErrorHandler" class="org.apache.camel.builder.NoErrorHandlerBuilder"/>

<camelContext errorHandlerRef="noErrorHandler" xmlns="http://camel.apache.org/schema/spring">
  ...
</camelContext>
---------------------------------------------------------------------------------------------

or also from *Camel 2.3.0 onwards*

[source,xml]
---------------------------------------------------------------
<camel:errorHandler id="noErrorHandler" type="NoErrorHandler"/>

<camel:camelContext errorHandlerRef="noErrorHandler">
  ...
</camel:camelContext>
---------------------------------------------------------------

[[ErrorHandler]]
link:transactionerrorhandler.html[TransactionErrorHandler]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The link:transactionerrorhandler.html[TransactionErrorHandler] is the
default error handler in Camel for transacted routes.

TIP:If you have marked a route as transacted using the *transacted* DSL then
Camel will automatic use a
link:transactionerrorhandler.html[TransactionErrorHandler]. It will try
to lookup the global/per route configured error handler and use it if
its a `TransactionErrorHandlerBuilder` instance. If not Camel will
automatic create a temporary
link:transactionerrorhandler.html[TransactionErrorHandler] that
overrules the default error handler. This is convention over
configuration.

[[ErrorHandler-Featuressupportbyvariouss]]
Features support by various link:error-handler.html[Error Handler]s
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Here is a breakdown of which features is supported by the
link:error-handler.html[Error Handler](s):

[width="100%",cols="20%,80%",options="header",]
|=======================================================================
Feature |Supported by the following link:error-handler.html[Error Handler]

|all scopes |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|onException |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|onWhen |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|continued |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|handled |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|Custom ExceptionPolicy |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|useOriginalBody |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|retryWhile |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|onRedelivery |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|RedeliveryPolicy |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|asyncDelayedRedelivery |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|redeliverWhileStopping |link:defaulterrorhandler.html[DefaultErrorHandler],
link:transactionerrorhandler.html[TransactionErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|dead letter queue |link:dead-letter-channel.html[Dead Letter Channel]

|onPrepareFailure |link:defaulterrorhandler.html[DefaultErrorHandler],
link:dead-letter-channel.html[Dead Letter Channel]

|=======================================================================

See link:exception-clause.html[Exception Clause] documentation for
documentation of some of the features above.

[[ErrorHandler-Scopes]]
Scopes
^^^^^^

The error handler is scoped as either

* global
* per route

The following example shows how you can register a global error handler
(in this case using the logging handler)

[source,java]
---------------------------------------------------------------
RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        // use logging error handler
        errorHandler(loggingErrorHandler("com.mycompany.foo"));
 
        // here is our regular route
        from("seda:a").to("seda:b");
    }
};
---------------------------------------------------------------

The following example shows how you can register a route specific error
handler; the customized logging handler is only registered for the route
from link:endpoint.html[Endpoint] *seda:a*

[source,java]
---------------------------------------------------------------
RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        // this route is using a nested logging error handler
        from("seda:a")
            // here we configure the logging error handler
            .errorHandler(loggingErrorHandler("com.mycompany.foo"))
            // and we continue with the routing here
            .to("seda:b");
 
        // this route will use the default error handler (DeadLetterChannel)
        from("seda:b").to("seda:c");
    }
};
---------------------------------------------------------------

[[ErrorHandler-Springbasedconfiguration]]
Spring based configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^

*Java DSL vs. Spring DSL*
The error handler is configured a bit differently in Java DSL and Spring
DSL. Spring DSL relies more on standard Spring bean configuration
whereas Java DSL uses fluent builders.


The error handler can be configured as a spring bean and scoped in:

* global (the camelContext tag)
* per route (the route tag)
* or per policy (the policy/transacted tag)

The error handler is configured with the `errorHandlerRef` attribute.

TIP:*Error Handler Hierarchy*
The error handlers is inherited, so if you only have set a global error
handler then its use everywhere. But you can override this in a route
and use another error handler.

[[ErrorHandler-Springbasedconfigurationsample]]
Spring based configuration sample
+++++++++++++++++++++++++++++++++

In this sample we configure a link:dead-letter-channel.html[Dead Letter
Channel] on the route that should redeliver at most 3 times and use a
little delay before retrying. First we configure the reference to *myDeadLetterErrorHandler* using
the `errorHandlerRef` attribute on the `route` tag.

Then we configure *myDeadLetterErrorHandler* that is our
link:dead-letter-channel.html[Dead Letter Channel]. This configuration
is standard Spring using the bean element. +
 And finally we have another spring bean for the redelivery policy where
we can configure the options for how many times to redeliver, delays
etc.

From Camel 2.3.0, camel provides a customer bean configuration for the
Error Handler, you can find the examples here.

[[ErrorHandler-Usingthetransactionalerrorhandler]]
Using the transactional error handler
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The transactional error handler is based on spring transaction. This
requires the usage of the camel-spring component. +
 See link:transactional-client.html[Transactional Client] that has many
samples for how to use and transactional behavior and configuration with
this error handler.

[[ErrorHandler-Seealso]]
See also
^^^^^^^^

* link:error-handling-in-camel.html[Error handling in Camel] for
introduction and background material on error handling in Camel
* link:dead-letter-channel.html[Dead Letter Channel] for the dead letter
error handler
* link:defaulterrorhandler.html[DefaultErrorHandler] for the default
error handler in Camel
* link:transactionerrorhandler.html[TransactionErrorHandler] for the
default error handler for transacted routes
* link:transactional-client.html[Transactional Client] for transactional
behavior
* link:exception-clause.html[Exception Clause] as it supports *handling*
thrown exceptions
* link:try-catch-finally.html[Try Catch Finally] for try ... catch ...
finally as DSL you can use in the routing