/messenger-retry-failures

name: messenger-retry-failures
description: Handle message failures with retry strategies, failure transport, and recovery in Symfony Messenger (Recoverable/Unrecoverable exceptions)
capabilities: [read, search, edit, shell]
tags: [messenger]
# projected by `bun run build` — do not edit by hand
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
  - Bash

Messenger Retry Failures (Symfony)

Use when

• A handler fails and you must decide between retrying and giving up.
• Tuning `retry_strategy` (`max_retries`, `delay`, `multiplier`, `max_delay`) for a transport.
• Inspecting, retrying, or removing messages in the failure transport.
• Alerting when a message fails for good.

Default workflow

1. Classify each failure: `UnrecoverableMessageHandlingException` when retrying cannot help, `RecoverableMessageHandlingException` when the cause is transient. 2. Set `retry_strategy` per transport and point `failure_transport` to a dedicated queue. 3. Implement `RetryStrategyInterface` only when the built-in backoff is not enough, and register it through `retry_strategy.service`. 4. Make the handler idempotent, with a stable idempotency key for external calls. 5. Triage with `messenger:failed:show`, then `messenger:failed:retry` or `messenger:failed:remove`. 6. Subscribe to `WorkerMessageFailedEvent` and alert only when `willRetry()` is false.

Guardrails

• Never retry what cannot succeed, such as invalid input or a declined card.
• Keep `max_retries` modest (3-5 usually) with exponential backoff, so a failing service is not hammered.
• `retryDelay` and `forceRetry` on the recoverable exception are marked 8.1+ in the reference, and `forceRetry: true` goes past `max_retries`: verify the version before relying on them.
• `messenger:failed:retry` is interactive unless `--force`: read the message with `-vv` first.

Progressive disclosure

• Use this file for execution posture and risk controls.
• Open references when deep implementation details are needed.

Output contract

• The exception class chosen for each failure mode of the handler.
• Retry settings per transport, and the failure transport.
• The failed-message runbook (show, retry, remove) and the alert on final failure.

References

• `reference.md`