---
title: "Feature: #110230 - Retry and park failed Messenger messages"
manual: "TYPO3 Core Changelog"
version: "main"
permalink: "https://docs.typo3.org/permalink/changelog:feature-110230-1784620000"
source: "Changelog/15.0/Feature-110230-RetryAndParkFailedMessengerMessages.rst"
typo3-version: "15.0"
typo3-major: 15
type: "feature"
issue: 110230
forge: "https://forge.typo3.org/issues/110230"
tags: ["CLI", "Database", "PHP-API", "ext:core"]
rendered: "2026-11-14T17:17:53+00:00"
---

# Feature: #110230 - Retry and park failed Messenger messages {#feature-110230-1784620000}

See [forge#110230](https://forge.typo3.org/issues/110230)

## Description {#description}

A message consumed asynchronously by a Symfony Messenger worker
(`typo3 messenger:consume <transport>`) was lost when its handler failed.
TYPO3 now provides an opt-in failure transport together with a per-transport
retry strategy, and the console commands to inspect, retry and remove the
parked messages.

The failure handling applies only to asynchronous processing by a worker. It
reacts to the `\Symfony\Component\Messenger\Event\WorkerMessageFailedEvent`
of the worker, using the listeners of Symfony Messenger. A synchronous dispatch,
including the `SyncTransport`, is never affected.

## Enabling the failure transport {#enabling-the-failure-transport}

The failure transport is disabled by default. Name the transport failed messages
should be parked in:

**config/system/settings.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['failure_transport'] = 'failed';
```

TYPO3 ships a `failed` transport that stores the messages in the table
`sys_messenger_messages` with the queue name `failed`, so no additional
database table is required.

A failure transport is not consumed by `messenger:consume`, so a worker
started without a transport name still consumes the `doctrine` transport
only. Parked messages are handled with the `messenger:failed:*` commands.

## Per-transport failure transport {#per-transport-failure-transport}

By default every transport shares the global failure transport. A transport can
use its own failure transport, or opt out of failure handling, with the option
`failure_transport` keyed by the transport name:

**config/system/settings.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['failure_transport'] = 'failed';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['transports'] = [
    // failures of the "email" transport go to a dedicated failure transport
    'email' => ['failure_transport' => 'failed_email'],
    // the "reporting" transport opts out of failure handling
    'reporting' => ['failure_transport' => ''],
];
```

A transport without the option uses the global failure transport. An empty value
disables the failure transport for that transport.

A failure transport must be registered as a messenger sender and tagged
`messenger.failure_transport`, so that the `messenger:failed:*`
commands can operate on it:

**EXT:my_extension/Configuration/Services.yaml**

```yaml
services:
  MyVendor\MyExtension\Messenger\FailedEmailTransport:
    class: Symfony\Component\Messenger\Bridge\Doctrine\Transport\DoctrineTransport
    factory: [ '@TYPO3\CMS\Core\Messenger\DoctrineTransportFactory', 'createTransport' ]
    arguments:
      $options:
        queue_name: 'failed_email'
    tags:
      - { name: 'messenger.sender', identifier: 'failed_email' }
      - { name: 'messenger.failure_transport', identifier: 'failed_email' }
```

To decide the failure transport of a transport at runtime, listen to the new
PSR-14 event `\TYPO3\CMS\Core\Messenger\Event\ResolveFailureTransportEvent`.
It carries the name of the transport the message failed on and the failure
transport resolved from the configuration. Setting `null` disables the
failure transport for that transport:

**EXT:my_extension/Classes/EventListener/RouteImportFailures.php**

```php
use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\Messenger\Event\ResolveFailureTransportEvent;

final class RouteImportFailures
{
    #[AsEventListener]
    public function __invoke(ResolveFailureTransportEvent $event): void
    {
        if ($event->getReceiverName() === 'import') {
            $event->setFailureTransportName('failed_import');
        }
    }
}
```

## Retrying before parking {#retrying-before-parking}

A transport can retry a failed message a number of times before it is sent to
the failure transport. Configure a retry strategy per transport, keyed by the
transport name:

**config/system/settings.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['messenger']['transports']['doctrine']['retry_strategy'] = [
    'max_retries' => 3,
    'delay' => 1000,    // milliseconds before the first retry
    'multiplier' => 2,  // the delay is multiplied by this for each retry
    'max_delay' => 0,   // maximum delay in milliseconds, 0 = no limit
];
```

Unlike in Symfony applications, a transport without a `retry_strategy` is
not retried, so existing transports keep their behaviour. A failed message is
sent straight to the failure transport, if one is configured.

## Console commands {#console-commands}

Three commands operate on the failure transport:

-   `messenger:failed:show` lists the parked messages, or shows a single
    message when given its id.
-   `messenger:failed:retry` handles one or more messages again, by id or
    all pending messages with `--force`, as received from the transport
    they failed on. Handlers that succeeded before are skipped. A message that
    succeeds is removed from the failure transport. A message that fails again
    is parked again with the new error, and the command exits with a failure
    code.
-   `messenger:failed:remove` deletes the given messages from the failure
    transport.

None of the commands are offered as scheduler tasks.

## Impact {#impact}

Asynchronous message processing no longer loses a message whose handler fails:
the message is retried according to the retry strategy of its transport and, if
it still fails, parked in the failure transport, where it can be inspected,
retried or removed on the command line.
