Skip to content

Dead Letters

Dead Letters lists the pipeline transitions that failed and will not be retried until you resolve them. Route: /operations/throughput?view=failed

The page opens with the line “Transitions that failed and will not be retried until you resolve them.” It follows the tenant chosen in the sidebar tenant selector.

ColumnWhat it shows
RepositoryThe owner/name the transition belongs to.
IssueThe issue number (#123). Select it to open the issue’s work-item sheet.
TransitionThe from-state and to-state as status chips, joined by an arrow. — stands in for the from-state when there is none.
AgentThe agent that attempted the transition, or — when none is recorded.
ErrorThe error, truncated. Hover for the full text.
CreatedHow long ago the dead letter was recorded.

Each row has a Resolve button. It marks that dead letter resolved and shows the toast “Dead letter marked resolved”. The row leaves the list.

Resolve all sits in the page header and appears only when at least one dead letter exists. It opens the Resolve all dead letters dialog with the message “Mark all N dead letters resolved? They will not be retried.” Choose Resolve all to confirm or Cancel to leave the list alone. After it succeeds, the list returns to the first page.

Resolving never replays the transition. It acknowledges the record and Colony will not retry it.

The page has no Retry control. To retry a dead letter, call the API:

POST /pipeline/dead-letters/{id}/retry

This endpoint takes a signed-in dashboard session, not a connection token, and needs the Operations grant. If your organization has more than one tenant, add ?tenant= with the tenant’s id.

Retry resolves the record and restarts the issue from new. It does not replay the recorded target state. See Recover a Dead-Lettered Issue for when that is the right call, and the API reference for the full endpoint list.

The list shows 50 dead letters per page, with Previous and Next controls and a “Showing X–Y of N” line. The controls appear only when there is more than one page.

When nothing is waiting, the page says “No dead letters. Every transition has landed.” and links to the Ledger, which shows what’s currently in flight.

A dead letter is not the same as the failure-blocked issue state. A dead letter is a record of one transition that failed. failure-blocked is a state an issue itself sits in. An issue can have a dead letter without being failure-blocked, and resolving a dead letter does not move an issue out of any state.