symfony · VincentLanglet · Oct 2, 2025 · Oct 3, 2025
diff --git a/UPGRADE-7.4.md b/UPGRADE-7.4.md
@@ -92,6 +92,11 @@ Mime

 * Deprecate implementing `__sleep/wakeup()` on `AbstractPart` implementations; use `__(un)serialize()` instead

+Messenger
+---------
+
+* Add `forceRetry()` method to `RecoverableExceptionInterface`
+
 MonologBridge
 -------------


diff --git a/src/Symfony/Component/Messenger/CHANGELOG.md b/src/Symfony/Component/Messenger/CHANGELOG.md
@@ -8,6 +8,7 @@ CHANGELOG
 * Allow any `ServiceResetterInterface` implementation in `ResetServicesListener`
 * Add `Symfony\Component\Messenger\Middleware\AddDefaultStampsMiddleware` and `Symfony\Component\Messenger\Message\DefaultStampsProviderInterface`
 * Add the possibility to configure exchange to exchange bindings in AMQP transport
+ * Add `forceRetry()` method to `RecoverableExceptionInterface`

 7.3
 ---

diff --git a/src/Symfony/Component/Messenger/EventListener/SendFailedMessageForRetryListener.php b/src/Symfony/Component/Messenger/EventListener/SendFailedMessageForRetryListener.php
@@ -116,7 +116,7 @@ public static function getSubscribedEvents(): array

    private function shouldRetry(\Throwable $e, Envelope $envelope, RetryStrategyInterface $retryStrategy): bool
    {
-        if ($e instanceof RecoverableExceptionInterface) {
+        if ($e instanceof RecoverableExceptionInterface && (!method_exists($e, 'forceRetry') || $e->forceRetry())) {
            return true;
        }

@@ -125,7 +125,9 @@ private function shouldRetry(\Throwable $e, Envelope $envelope, RetryStrategyInt
        if ($e instanceof HandlerFailedException) {
            $shouldNotRetry = true;
            foreach ($e->getWrappedExceptions() as $nestedException) {
-                if ($nestedException instanceof RecoverableExceptionInterface) {
+                if ($nestedException instanceof RecoverableExceptionInterface
+                    && (!method_exists($nestedException, 'forceRetry') || $nestedException->forceRetry())
+                ) {
                    return true;
                }


diff --git a/src/Symfony/Component/Messenger/Exception/RecoverableExceptionInterface.php b/src/Symfony/Component/Messenger/Exception/RecoverableExceptionInterface.php
@@ -20,6 +20,7 @@
 * @author Jérémy Derussé <jeremy@derusse.com>
 *
 * @method int|null getRetryDelay() The time to wait in milliseconds
+ * @method bool     forceRetry()    If the worker should retry even if it goes over the max retry limit
 */
 interface RecoverableExceptionInterface extends \Throwable
 {

diff --git a/src/Symfony/Component/Messenger/Exception/RecoverableMessageHandlingException.php b/src/Symfony/Component/Messenger/Exception/RecoverableMessageHandlingException.php
@@ -18,13 +18,23 @@
 */
 class RecoverableMessageHandlingException extends RuntimeException implements RecoverableExceptionInterface
 {
-    public function __construct(string $message = '', int $code = 0, ?\Throwable $previous = null, private readonly ?int $retryDelay = null)
-    {
+    public function __construct(
+        string $message = '',
+        int $code = 0,
+        ?\Throwable $previous = null,
+        private readonly ?int $retryDelay = null,
+        private readonly bool $forceRetry = true,
+    ) {
        parent::__construct($message, $code, $previous);
    }

    public function getRetryDelay(): ?int
    {
        return $this->retryDelay;
    }
+
+    public function forceRetry(): bool
+    {
+        return $this->forceRetry;
+    }
 }
diff --git a/...Symfony/Component/Messenger/Tests/EventListener/SendFailedMessageForRetryListenerTest.php b/...Symfony/Component/Messenger/Tests/EventListener/SendFailedMessageForRetryListenerTest.php
@@ -15,6 +15,7 @@
 use PHPUnit\Framework\TestCase;
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\DependencyInjection\Container;
+use Symfony\Component\DependencyInjection\ContainerInterface;
 use Symfony\Component\Messenger\Envelope;
 use Symfony\Component\Messenger\Event\WorkerMessageFailedEvent;
 use Symfony\Component\Messenger\Event\WorkerMessageRetriedEvent;
@@ -201,6 +202,29 @@ public static function provideRetryDelays(): iterable
        ];
    }

+    public function testRetryIsOnlyAllowedWhenPermittedByRetryStrategy()
+    {
+        $senderLocator = $this->createMock(ContainerInterface::class);
+        $senderLocator->expects($this->never())->method('has');
+        $senderLocator->expects($this->never())->method('get');
+
+        $retryStrategy = $this->createMock(RetryStrategyInterface::class);
+        $retryStrategy->expects($this->once())->method('isRetryable')->willReturn(false);
+        $retryStrategy->expects($this->never())->method('getWaitingTime');
+
+        $retryStrategyLocator = $this->createMock(ContainerInterface::class);
+        $retryStrategyLocator->expects($this->once())->method('has')->willReturn(true);
+        $retryStrategyLocator->expects($this->once())->method('get')->willReturn($retryStrategy);
+
+        $listener = new SendFailedMessageForRetryListener($senderLocator, $retryStrategyLocator);
+
+        $exception = new RecoverableMessageHandlingException('retry', forceRetry: false);
+        $envelope = new Envelope(new \stdClass());
+        $event = new WorkerMessageFailedEvent($envelope, 'my_receiver', $exception);
+
+        $listener->onMessageFailed($event);
+    }
+
    public function testEnvelopeIsSentToTransportOnRetry()
    {
        $exception = new \Exception('no!');