Error Channel and Dead Letter

Error Channel

Ecotone comes with solution that allow to push Error Messages to error channel. Depending on what subscribing to error channel you may provide different behaviour. From logging, storing or even discarding the message.

Error Channel

The error channel is channel defined for handling failed messages. As a default it's turned off. We may set up error channel for specific consumer

- Symfony

- Laravel

- Lite

Setting up Error Channel means that 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.

Manually Handling Error Messages from Error Channel

After setting it up default error channel to "errorChannel" we may subscribe to the errors by setting up ServiceActivator:

public function handle(ErrorMessage $errorMessage): void
    // do something with ErrorMessage

Service Activator are endpoints like Command Handlers, however they are not exposed using Command/Event/Query Buses. You may use them for internal handling.

Dbal Dead Letter

Ecotone comes with full support for managing full life cycle of a error message by using Dbal Module.

  • Store failed Message with all details about the exception

  • Allow for reviewing error Messages

  • Allow for deleting and replaying error Message back to the Asynchronous Message Channels


public function errorConfiguration()
    return ErrorHandlerConfiguration::createWithDeadLetterChannel(
        //  retry strategy
        RetryTemplateBuilder::exponentialBackoff(1000, 10)
        // if retry strategy will not recover, then send here

If you would set up "nullChannel" in place of "dbal_dead_letter", then all Message that can't be retried with success would be discared.

Dead Letter Console Commands


Get more details about existing commands

bin/console ecotone:deadletter:help

Listing Error Messages

Listing current error messages

bin/console ecotone:deadletter:list

Show Details About Error Message

Get more details about given error message

bin/console ecotone:deadletter:show {messageId}

Replay Error Message

Replay error message. It will return to previous channel for consumer to pick it up and handle again.

bin/console ecotone:deadletter:replay {messageId}

Replay All Messages

Replaying all the error messages.

bin/console ecotone:deadletter:replayAll

Delete Message

Delete given error message

bin/console ecotone:deadletter:delete {messageId}

Turn off Dbal Dead Letter

public function dbalConfiguration()
    return DbalConfiguration::createWithDefaults()

Managing Multiple Ecotone Applications

The above solution requires running Console Line Commands. If we want however, we can manage all our Error Messages from one place using Ecotone Pulse.

This is especially useful when we've multiple Applications, so we can go to single place and see if any Application have failed to process Message.

Last updated