# Error Channel
Error Channel
`Ecotone` comes with solution called Error Channel.\
Error Channel is a place where unrecoverable Errors can go, this way we can preserve Error Messages even if we can't handle them anyhow at given moment.\
Error Channel may log those Messages, store them in database, push them to some Asynchronous Channel, it all depends on what Handler we will connect to the Error Channel.
## Error Channel Flow
On the high level Error Channel works as follows:
Message is sent to Error Channel after failing
1. Message Consumer is polling Messages from the Queue and executing related Message Handlers.
2. When execution of given Handler fails, Error is propagated back to Message Consumer
3. Message Consumer based on the configuration sends it to related Error Channel
## Configuration
Error Channel can be configured per Message Consumer, or globally as default Error Channel for all Message Consumers:
* [Set up default error channel for all consumers](https://docs.ecotone.tech/messaging/service-application-configuration#ecotone-core-configuration)
\- [Symfony](https://docs.ecotone.tech/modules/symfony/symfony-ddd-cqrs-event-sourcing#defaulterrorchannel)
\- [Laravel](https://docs.ecotone.tech/modules/laravel/laravel-ddd-cqrs-event-sourcing#defaulterrorchannel)
\- [Lite](https://docs.ecotone.tech/modules/ecotone-lite#withdefaulterrorchannel)
{% tabs %}
{% tab title="Symfony" %}
**config/packages/ecotone.yaml**
```yaml
ecotone:
defaultErrorChannel: "errorChannel"
```
{% endtab %}
{% tab title="Laravel" %}
**config/ecotone.php**
```php
return [
'defaultErrorChannel' => 'errorChannel',
];
```
{% endtab %}
{% tab title="Lite" %}
```php
$ecotone = EcotoneLite::bootstrap(
configuration: ServiceConfiguration::createWithDefaults()
->withDefaultErrorChannel('errorChannel')
);
```
{% endtab %}
{% endtabs %}
* [Set up for specific consumer](https://docs.ecotone.tech/asynchronous-handling#static-configuration)
```php
class Configuration
{
#[ServiceContext]
public function configuration() : array
{
return [
// For Message Consumer orders, configure error channel
PollingMetadata::create("orders")
->setErrorChannelName("errorChannel")
];
}
}
```
{% hint style="info" %}
Setting up Error Channel means that [Message Consumer](https://docs.ecotone.tech/messaging/contributing-to-ecotone/demo-integration-with-sqs/message-consumer-and-publisher#message-consumer) will send Error Message to error channel and then continue handling next messages.\
\
After sending Error Message to Error Channel, message is considered handled as long as Error Handler does not throw exception.
{% endhint %}
## Handling Error Messages
### Manual Handling
To handle incoming Error Messages, we can bind to our defined Error Channel using [ServiceActivator](https://docs.ecotone.tech/messaging/messaging-concepts):
```php
#[InternalHandler("errorChannel")]
public function handle(ErrorMessage $errorMessage): void
{
// handle exception
$exception = $errorMessage->getExceptionMessage();
}
```
{% hint style="info" %}
Internal Handlers are endpoints like Command Handlers, however they are not exposed using Command/Event/Query Buses.\
You may use them for internal handling.
{% endhint %}
## Delayed Retries
Ecotone provides inbuilt retry mechanism, in case of failure Error Message will be resent to its original Message Channel with a delay. This way we will give application a chance to self-heal and return to good state.
Using inbuilt retry mechanism to resend Message with delay
To configure Delayed Retries we need to set up Error Configuration and connect it to our Error Channel:
```php
#[ServiceContext]
public function errorConfiguration()
{
return ErrorHandlerConfiguration::create(
"errorChannel",
RetryTemplateBuilder::exponentialBackoff(1000, 10)
->maxRetryAttempts(3)
);
}
```
### Discarding all Error Messages
If for some cases we want to discard Error Messages, we can set up error channel to default inbuilt one called **"nullChannel"**.\
That may be used in combination of retries, if after given attempt Message is still not handled, then discard:
```php
#[ServiceContext]
public function errorConfiguration()
{
return ErrorHandlerConfiguration::createWithDeadLetterChannel(
"errorChannel",
RetryTemplateBuilder::exponentialBackoff(1000, 10)
->maxRetryAttempts(3),
// if retry strategy will not recover, then discard
"nullChannel"
);
}
```
## Dbal Dead Letter
Ecotone comes with full support for managing full life cycle of a error message.\
This allows us to store Message in database for later review. Then we can review the Message, replay it or delete.
Using Dead Letter for storing Error Message
\
Read more in next [section](https://docs.ecotone.tech/modelling/recovering-tracing-and-monitoring/resiliency/error-channel-and-dead-letter/dbal-dead-letter).
{% hint style="success" %}
Dead Letter can be combined with Delayed Retries, to store only Error Messages that can't self-heal.\
Read more in related section.
{% endhint %}
## Command Bus Error Channel
Route failed synchronous commands to dedicated error handling with a single `#[ErrorChannel]` attribute. Instead of catching exceptions in each handler and manually routing to error handling, declare the error channel once. Failed messages are automatically routed for retry, logging, or dead-letter processing.
**You'll know you need this when:**
* Failed commands need specific error handling: alerting, manual review, or audit trails
* Payment or financial operations require failure tracking for compliance
* You receive webhooks and need to handle failures gracefully instead of throwing exceptions
* Scattered try/catch blocks in handlers are becoming unmanageable
* Different command categories need different error handling strategies
{% hint style="success" %}
Command Bus Error Channel is available as part of **Ecotone Enterprise.**
{% endhint %}
### Command Bus with Error Channel
To set up Error Channel for Command Bus, we will extend Command Bus with our Interface and add ErrorChannel attribute.
Command Bus with Dead Letter
```php
#[ErrorChannel("dbal_dead_letter")]
interface ResilientCommandBus extends CommandBus
{
}
```
Now instead of using **CommandBus**, we will be using **ResilientCommandBus** for sending Commands.\
Whenever failure will happen, instead being propagated, it will now will be redirected to our Dead Letter and stored in database for later review.
### Command Bus with Error Channel and Instant Retry
We can extend our Command Bus with Error Channel by providing instant retries.\
This way we can do automatic retries before we will consider Message as failed and move it to the Error Channel. This way we give ourselves a chance of self-healing automatically in case of transistent errors, like database or network exceptions.
Now instead of using **CommandBus**, we will be using **ResilientCommandBus** for sending Commands.\
Whenever failure will happen, instead being propagated, it will now will be redirected to our Dead Letter and stored in database for later review.
### Command Bus with Asynchronous Error Channel
Instead of pushing Message to Error Channel, we can push it to Asynchronous Message Channel from which Message will be consumed and retried again. This way in case of failure we can make it possible for Message to be retried and end up self-healing.
Command Bus with Asynchronous Error Channel
```php
#[ErrorChannel("async_channel")]
interface ResilientCommandBus extends CommandBus
{
}
```
and then for use RabbitMQ Message Channel:
```php
final readonly class EcotoneConfiguration
{
#[ServiceContext]
public function databaseChannel()
{
return AmqpBackedMessageChannelBuilder::create('orders');
}
}
```
{% hint style="success" %}
It's good practice to use different Message Channel implementation than the storage used during process the Message. For example if our processing requires database connection and our database went down, then if our configured channel is RabbitMQ channel, then we will be able to push those Messages into the Queue instead of failing.
{% endhint %}
### Command Bus with Asynchronous Error Channel and Delayed Retries
We can combine Asynchronous Error Channel together with delayed retries, creating robust solution, that our Application is able to self-heal from transistent errors even if they take some period of time.\
For example if our calling some external Service fails, or database went down, then we may receive the same error when Message is retrieved by Async Channel. However if we will delay that by 20 seconds, then there is huge chance that everything will get back on track, and the Application will self-heal automatically.
Command Bus with Asynchronous Error Channel and delayed retries
Command Bus configuration:
```php
#[ErrorChannel("async_channel")]
interface ResilientCommandBus extends CommandBus
{
}
```
And delayed retry configuration:
```php
#[ServiceContext]
public function errorConfiguration()
{
return ErrorHandlerConfiguration::create(
"async_channel",
RetryTemplateBuilder::exponentialBackoff(1000, 10)
->maxRetryAttempts(3)
);
}
```
{% hint style="success" %}
Of course we could add Dead Letter channel for our delayed retries configuration. Closing the full flow, that even if in case delayed retries failed, we will end up with Message in Dead Letter.
{% endhint %}
