messenger-retry-failures · diff
git:20261005.042befb to git:20261005.51f9253
17 added, 12 removed. Audit A to A.
---
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
- - Implementing asynchronous workflows with Messenger/Scheduler/Cache.
- - Stabilizing retries and failure transports.
+ - 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. Define async contract and delivery semantics.
- 2. Implement idempotent handlers and routing strategy.
- 3. Configure retries, failure transport, and observability.
- 4. Validate success/failure replay scenarios.
+ 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
- - Assume at-least-once delivery, not exactly-once.
- - Keep handlers deterministic and side-effect aware.
- - Surface poison-message handling strategy.
+ - 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
- - Async config/handlers updated.
- - Retry/failure policy decisions.
- - Operational validation evidence.
+ - 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`