messenger-retry-failures

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