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.
Dead letter table
Section titled “Dead letter table”| Column | What it shows |
|---|---|
| Repository | The owner/name the transition belongs to. |
| Issue | The issue number (#123). Select it to open the issue’s work-item sheet. |
| Transition | The from-state and to-state as status chips, joined by an arrow. — stands in for the from-state when there is none. |
| Agent | The agent that attempted the transition, or — when none is recorded. |
| Error | The error, truncated. Hover for the full text. |
| Created | How long ago the dead letter was recorded. |
Resolve
Section titled “Resolve”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.
Retry is API-only
Section titled “Retry is API-only”The page has no Retry control. To retry a dead letter, call the API:
POST /pipeline/dead-letters/{id}/retryThis 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.
Pagination
Section titled “Pagination”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.
Empty state
Section titled “Empty state”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.
Dead letters and failure-blocked
Section titled “Dead letters and failure-blocked”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.
Next steps
Section titled “Next steps”- Recover a Dead-Lettered Issue covers diagnosis and the retry procedure.
- Troubleshooting lists other places a stuck pipeline shows up.
- Write Queue tracks VCS writes that did not land, a different failure from a failed transition.