messenger-retry-failures — Claude Code skill: Symfony Messenger
messenger-retry-failures sorts out failed Symfony Messenger handlers: whether a message deserves another attempt, when it goes straight to the failure transport, and how to pull it back.
MIT ★ 234 updated 2026-10-05
npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a claude-codeWhat messenger-retry-failures does
The skill treats a failed message as a triage question. Every error gets a class: UnrecoverableMessageHandlingException when another attempt cannot help, RecoverableMessageHandlingException when the cause may pass on its own.
Then come the transport settings. retry_strategy gets max_retries, delay, multiplier and max_delay, and failures land in a failure_transport of their own. A custom RetryStrategyInterface is for the cases where built-in backoff falls short; it registers under retry_strategy.service. Handlers are expected to be idempotent, with a stable key for outbound calls.
Recovery runs through messenger:failed:show, then messenger:failed:retry or messenger:failed:remove. Watch the version: forceRetry: true and retryDelay on the exception are flagged 8.1+, and forceRetry jumps past max_retries, so older setups cannot use either. The retry command asks for confirmation unless you pass --force, which is why the message gets read with -vv first. For alerting, the skill hooks WorkerMessageFailedEvent and fires only when willRetry() returns false.
What it helps with
- sort handler errors into recoverable and unrecoverable buckets
- tune backoff so a failing service is not hammered
- move permanently failed messages into a separate queue
- inspect, retry or drop one message from the failure transport
- alert on final failure only, skipping intermediate attempts
Example prompts for the agent
- Work out why
SendInvoiceHandlerkeeps failing and pick an exception for each case. - Set up
retry_strategyon theasynctransport and route failures to their own queue. - Show me what is stuck with
messenger:failed:show, then remove the messages with broken payloads.
How to install messenger-retry-failures
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a claude-code2Manually: put the files in place
~/.claude/skills/messenger-retry-failures/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/messenger-retry-failures/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a codex2Manually: put the files in place
.agents/skills/messenger-retry-failures/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a cursor2Manually: put the files in place
.cursor/skills/messenger-retry-failures/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dev-toolings/superpowers-symfony content/skills/messenger-retry-failures2Manually: put the files in place
.github/skills/messenger-retry-failures/SKILL.md1Skills CLI (Vercel)
npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a gemini-cli2Platform CLI
gemini skills install https://github.com/dev-toolings/superpowers-symfony --path content/skills/messenger-retry-failuresManually: put the files in place
.devin/skills/messenger-retry-failures/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about messenger-retry-failures
How do I install messenger-retry-failures in Claude Code?
Run npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a claude-code. The skill file lands at ~/.claude/skills/messenger-retry-failures/SKILL.md.
What does messenger-retry-failures do?
It settles the retry-or-give-up decision for a Symfony Messenger handler, configures the retry strategy and failure transport, and walks through the messenger:failed:* commands for stuck messages.
What is the difference between Recoverable and Unrecoverable exceptions?
UnrecoverableMessageHandlingException tells Messenger that retrying is pointless, for instance on invalid input. RecoverableMessageHandlingException marks a transient cause that a later attempt may survive.
Source text
SKILL.md · MIT
--- 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`
© dev-toolings · MIT · dev-toolings/superpowers-symfony