Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dev-toolings/superpowers-symfony --skill messenger-retry-failures -a claude-code
Open on GitHub

What 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 SendInvoiceHandler keeps failing and pick an exception for each case.
  • Set up retry_strategy on the async transport 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-code

2Manually: put the files in place

~/.claude/skills/messenger-retry-failures/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/messenger-retry-failures/

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

Similar skills

All skills for Backend and APIs →

From the same set51

The whole set →
e2e-panther-playwright The e2e-panther-playwright skill guides Symfony E2E tests with Panther for browser flows and Playwright for more involved cases. Use it when JavaScript behavior is beyond what WebTestCase can observe. CX Codex +1 ★ 234repo stars doctrine-relations Skill guides you through defining Doctrine relationships (OneToMany, ManyToMany, ManyToOne) with correct owning and inverse sides, cascade strategies, and N+1 query prevention. CX Codex +1 ★ 234repo stars doctrine-fetch-modes doctrine-fetch-modes guides Doctrine ORM and DBAL 4 query optimization in Symfony. Fixes N+1 queries, configures lazy loading, and implements DTO hydration. CX Codex +1 ★ 234repo stars api-platform-resources api-platform-resources is a Claude Code skill for configuring API Platform resources for REST and GraphQL. It activates for resource creation and changes to operations, pagination, or OpenAPI docs. CX Codex +1 ★ 234repo stars api-platform-state-providers Configures API Platform State Providers and Processors in Symfony. It helps decouple data retrieval and persistence from Doctrine entities. CX Codex +1 ★ 234repo stars api-platform-dto-resources The api-platform-dto-resources skill decouples your API contract from Doctrine entities in API Platform via Symfony's Object Mapper. CX Codex +1 ★ 234repo stars api-platform-filters api-platform-filters tells the agent how to wire search, range, date and boolean filters into API Platform collection endpoints in Symfony, and how to leave the deprecated attribute behind. CX Codex +1 ★ 234repo stars doctrine-performance-optimizer doctrine-performance-optimizer audits Doctrine ORM code in read-only mode to detect looped relation queries, evaluate fetch strategies, and suggest DTO hydration, batch processing, or database indexes. CX Codex ★ 234repo stars

Project sponsors

Companies that keep this analytics open