Skip to content

Handle failed queue messages ​

A message that fails max_attempts times becomes dead. Edge keeps dead messages for 14 days so you can see why they failed, fix the consumer, and put them back. Nothing is lost silently: each one also raises a queue.message.dead_lettered event.

None of this changes the live site.

The queue here is orders (que_01M4XB7Q2W8E5R3T6Y9U1I4O0P) on acme-marketing; see Process work in the background with a queue.

1. Get told when it happens ​

Subscribe a webhook to queue.message.dead_lettered. The event carries the message body, so * does not select it: name it, or queue.*. See Send events to a webhook.

2. See what failed ​

In the web app, open Distributions, select acme-marketing, and look at Queues: a queue with dead messages shows how many.

text
Show me the dead messages in the orders queue on acme-marketing and why they failed.
bash
edge queues peek que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status dead
bash
curl -s "https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/messages?status=dead" \
  -H "Authorization: Bearer $EDGE_TOKEN"

The agent runs edge_queue_peek:

json
{
  "status": "dead",
  "messages": [
    {
      "message_id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C",
      "attempts": 5,
      "last_error": "guest_status: the function answered 500",
      "dead_at": "2026-10-19T03:40:12+00:00",
      …
    }
  ]
}

Bodies are left out because they can hold personal data. Add --bodies (include_bodies=true) to see them; Edge logs who read them and how many. The batch runs behind last_error are in edge queues runs, and the function's own output is in its logs with source set to queue.

A message whose last_error is expired was never delivered within the queue's retention_days; it did not fail in your consumer.

3. Put them back, or delete them ​

After fixing the consumer, redrive puts dead messages back in the queue with their attempts reset. Purge deletes them for good. In the web app, the queue's row has Redrive dead and Purge dead; purge asks you to click twice.

text
Redrive the dead messages in the orders queue on acme-marketing.
bash
edge queues redrive que_01M4XB7Q2W8E5R3T6Y9U1I4O0P
# only some:
edge queues redrive que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --message msg_01M4XB9D3F6G8H1J4K7L0Z2X5C
# or delete them:
edge queues purge que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status dead
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/redrive \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/purge \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "dead", "confirm": true}'

The agent runs edge_queue_redrive ({"redriven": 3}) or edge_queue_purge ({"deleted": 3}). Purge cannot be undone, and it only touches the status you name: purging dead leaves waiting messages alone. Messages in a running batch are never purged.

Next ​

To stop new batches while you fix the consumer, pause the queue (Pause in the web app, edge queues update que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --paused true); messages keep arriving and wait for you. Limits lists how long each kind of message is kept.