> ## Content Index
> Fetch the complete content index at: https://shakeride.com/guides/llms.txt
> Use this file to discover other available public pages before exploring further.

# SQS dead-letter queue not working: the deep dive
- URL: https://shakeride.com/guides/sqs-dead-letter-queue-not-working-deep-dive/
- Published: 2026-09-21T08:00:00.000Z
- Updated: 2026-11-09T20:15:19.000Z
- Description: Every check, trap and redrive path behind a dead-letter queue that stays empty, on Amazon SQS, Azure Service Bus and Google Cloud Pub/Sub, with the commands to run.
- Author: Shakeride
- Tags: Event delivery, AWS, Azure, Google Cloud, SQS, Lambda, CloudWatch, Service Bus, Azure Functions, Azure Monitor, Pub/Sub, Cloud Run, Cloud Monitoring, #deep-dive

The two-minute version is [SQS dead-letter queue not working](https://shakeride.com/guides/sqs-dead-letter-queue-not-working/). This page keeps every detail.

A message that cannot be processed has to end somewhere a person can look at it. When it does not, it is retried until it expires and then it is simply gone, without an error anywhere. Amazon SQS, Azure Service Bus and Google Cloud Pub/Sub all offer a dead-letter destination, and each one fails silently in its own way.

## Recognise the failure pattern

The common symptom is a message that is processed repeatedly, then seems to disappear without reaching the queue the team calls its dead-letter queue. Other versions are a source queue that never drains, a dead-letter queue that stays empty while the consumer logs errors, or a whole batch that returns again because one record fails. These symptoms do not prove that the broker lost a message. They point to redrive configuration, receive behaviour, retention or consumer acknowledgement.

The three providers put the dead-letter decision in different places, and that is where to start:

- **Amazon SQS**: the source queue owns a `RedrivePolicy` naming the dead-letter queue ARN and `maxReceiveCount`. Without it, a failing message returns until the source retention period deletes it.
- **Azure Service Bus**: every queue and every topic subscription has a dead-letter subqueue that cannot be disabled. A message moves there after `MaxDeliveryCount` deliveries, but only if the consumer lets the delivery fail.
- **Google Cloud Pub/Sub**: the subscription owns a dead-letter policy naming a topic and `maxDeliveryAttempts`. Forwarding needs a permission most teams never grant, and the target topic needs a subscription of its own.

![Three lanes, one per provider, showing a failing message retried and then lost: an SQS queue without a RedrivePolicy, a Service Bus message completed after a caught error or expired without dead-lettering, and a Pub/Sub subscription whose service agent cannot publish to the dead-letter topic.](https://shakeride.com/guides/content/images/2026/11/sqs-dead-letter-queue-not-working-deep-dive-dlq-failure-paths.svg)

## Amazon SQS: inspect the source queue first

Request the attributes explicitly because `get-queue-attributes` returns an empty result when no attribute names are supplied. Read `RedrivePolicy` as JSON inside the returned string. Confirm that `deadLetterTargetArn` exactly names the intended queue and that `maxReceiveCount` is appropriate for the consumer's retry behaviour. Also note the source retention and visibility timeout. A very high maximum can make the dead-letter queue look broken simply because the message has not crossed the threshold yet.

Approximate message counts are eventually consistent and should be treated as operational clues, not a transaction ledger. Compare visible and in-flight messages over time. A growing in-flight count can mean consumers are receiving work but not deleting it before the visibility timeout. A visible count that repeatedly falls and rises can be a retry loop.

```bash
aws sqs get-queue-attributes \
  --queue-url https://sqs.us-east-1.amazonaws.com/123456789012/orders \
  --attribute-names QueueArn RedrivePolicy VisibilityTimeout MessageRetentionPeriod \
    ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible

```

```json
{
  "Attributes": {
    "QueueArn": "arn:aws:sqs:us-east-1:123456789012:orders",
    "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:123456789012:orders-dlq\",\"maxReceiveCount\":\"5\"}",
    "VisibilityTimeout": "60",
    "MessageRetentionPeriod": "345600",
    "ApproximateNumberOfMessages": "3",
    "ApproximateNumberOfMessagesNotVisible": "1"
  }
}

```

### Check the SQS dead-letter queue independently

Inspect the target queue by its URL, not a similar display name. Its `QueueArn` must match the ARN in the source `RedrivePolicy`. Standard queues must use a standard dead-letter queue, and FIFO queues must use a FIFO dead-letter queue. Check `RedriveAllowPolicy` as well. The default allows source queues in the same account and Region, but a policy set to `denyAll` or `byQueue` can prevent an unintended source from using it.

The dead-letter queue retention period must leave enough time for detection and investigation. Be careful when changing retention: SQS documents that a reduction can expire existing messages, and a retention change can take time to propagate. For standard queues, the original enqueue timestamp is retained when the message moves, so the dead-letter queue retention should normally exceed the source retention. FIFO queues reset the enqueue timestamp when the message moves.

```bash
aws sqs get-queue-attributes \
  --queue-url https://sqs.us-east-1.amazonaws.com/123456789012/orders-dlq \
  --attribute-names QueueArn RedriveAllowPolicy MessageRetentionPeriod ApproximateNumberOfMessages

```

```json
{
  "Attributes": {
    "QueueArn": "arn:aws:sqs:us-east-1:123456789012:orders-dlq",
    "RedriveAllowPolicy": "{\"redrivePermission\":\"allowAll\"}",
    "MessageRetentionPeriod": "1209600",
    "ApproximateNumberOfMessages": "2"
  }
}

```

### Trace the Lambda consumer and its acknowledgement

A message reaches the dead-letter queue only after receives that are not followed by a successful delete. If a consumer never polls the source queue, receive count does not rise. If it catches an error and deletes the message anyway, SQS considers the work complete and redrive never occurs. If processing takes longer than the visibility timeout, the same message can become visible and be delivered again while the first attempt still runs.

For an SQS-triggered Lambda function, list the event source mapping by source ARN and function. Confirm that `State` is `Enabled`, inspect `LastProcessingResult`, batch size and `FunctionResponseTypes`. By default, a failed Lambda batch makes every message in that batch visible again. Partial batch response requires application support and the `ReportBatchItemFailures` response type. Enabling the mapping option without returning the required batch item failures does not repair the handler.

```bash
aws lambda list-event-source-mappings \
  --event-source-arn arn:aws:sqs:us-east-1:123456789012:orders \
  --function-name orders-consumer \
  --query 'EventSourceMappings[].{UUID:UUID,State:State,Result:LastProcessingResult,BatchSize:BatchSize,Responses:FunctionResponseTypes}' \
  --output table

```

## Azure Service Bus: the dead-letter queue always exists

Service Bus never lacks a dead-letter queue: each queue has one at `orders/$deadletterqueue`, and each topic subscription has its own under the subscription path. So an empty dead-letter queue on Service Bus is never a missing resource. It means no message was dead-lettered, and there are three common reasons.

The first is the delivery threshold. A message is dead-lettered with the reason `MaxDeliveryCountExceeded` once its delivery count passes `maxDeliveryCount`, ten by default. In peek-lock mode the count rises when the consumer abandons the message or when its lock expires. The lock lasts `lockDuration`, one minute by default and five at most, so a handler that runs longer than the lock without renewing it produces duplicate deliveries rather than failures.

The second is expiry. When a message outlives its time to live, Service Bus drops it unless `deadLetteringOnMessageExpiration` is enabled on the queue or subscription. That setting is off by default, which makes expiry the most common way a message vanishes on Service Bus with nothing in the dead-letter subqueue.

```bash
az servicebus queue show \
  --resource-group rg-orders --namespace-name sb-orders --name orders \
  --query "{maxDeliveryCount:maxDeliveryCount, lockDuration:lockDuration, ttl:defaultMessageTimeToLive, deadLetterOnExpiry:deadLetteringOnMessageExpiration, active:countDetails.activeMessageCount, deadLettered:countDetails.deadLetterMessageCount}"

```

```json
{
  "active": 0,
  "deadLetterOnExpiry": false,
  "deadLettered": 0,
  "lockDuration": "PT1M",
  "maxDeliveryCount": 10,
  "ttl": "PT1H"
}

```

The third is the consumer, which decides whether a delivery fails. A client that receives in `ReceiveAndDelete` mode removes the message on receipt, so a crash afterwards loses it with no retry at all. An Azure Functions Service Bus trigger uses peek-lock and, with `autoCompleteMessages` left at its default of true, completes the message when the function returns. A function that catches the exception, logs it and returns normally therefore completes every poison message. Let the exception escape, or abandon or dead-letter the message explicitly with a reason the next reader can act on.

On a topic, also check what reaches the subscription at all. A message that matches no subscription filter is not dead-lettered: it is accepted by the topic and delivered nowhere. Inspect dead-lettered messages with Service Bus Explorer in the portal, in peek mode so the inspection itself does not settle them, and read their `DeadLetterReason` and `DeadLetterErrorDescription` properties.

## Google Cloud Pub/Sub: a dead-letter topic needs a subscription and a permission

On Pub/Sub, dead-lettering is a policy on the subscription: a dead-letter topic and `maxDeliveryAttempts`, between 5 and 100\. Pub/Sub counts a delivery attempt each time a pull message is not acknowledged before its ack deadline (ten seconds by default) or is nacked, and each time a push endpoint answers with a status outside the success codes. Without a dead-letter policy, an unacknowledged message is redelivered until the subscription's `messageRetentionDuration`, seven days by default, deletes it.

```bash
gcloud pubsub subscriptions describe orders-sub \
  --format="yaml(deadLetterPolicy,ackDeadlineSeconds,messageRetentionDuration,retryPolicy)"

```

```yaml
ackDeadlineSeconds: 10
deadLetterPolicy:
  deadLetterTopic: projects/shop-prod/topics/orders-dead-letter
  maxDeliveryAttempts: 5
messageRetentionDuration: 604800s
retryPolicy:
  maximumBackoff: 600s
  minimumBackoff: 10s

```

A policy that looks correct can still forward nothing. The forwarding is done by the Pub/Sub service agent of the project, `service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com`, which needs `roles/pubsub.publisher` on the dead-letter topic and `roles/pubsub.subscriber` on the source subscription. Without both bindings the message keeps being redelivered, the delivery attempts climb past the threshold and the dead-letter topic stays empty. The console shows a warning on the subscription; the CLI says nothing unless you read the IAM policies.

```bash
gcloud pubsub topics get-iam-policy orders-dead-letter --format=json
gcloud pubsub subscriptions get-iam-policy orders-sub --format=json

```

The second trap is the target itself. A Pub/Sub topic stores nothing for later: a message published to a topic with no subscription and no topic retention is discarded. Forwarding can succeed and the evidence still disappear, because nobody attached `orders-dead-letter-sub` to the dead-letter topic. Delivery attempt counts are also best effort, so do not assert an exact number in tests; assert that the message arrives on the dead-letter subscription.

For a Cloud Run service behind a push subscription, or an Eventarc Pub/Sub trigger, the dead-letter policy belongs on the push subscription that Pub/Sub or Eventarc created. Any response other than a success status counts as a failed attempt, so a service that answers 200 after catching an exception acknowledges the poison message just as surely as an Azure Function that returns normally.

## Apply the smallest configuration fix

Correct only the broken link, and put the change in infrastructure as code after containment so the next deployment does not restore the broken value. The examples use a threshold of five attempts; choose yours from the number of attempts that can succeed transiently without delaying investigation too long.

On **SQS**, attach the intended dead-letter queue to the source. If a Lambda batch retries successful records, update the handler to return failed item identifiers first, test that response, then enable `ReportBatchItemFailures` on the mapping. Treat these as one application change.

```bash
aws sqs set-queue-attributes \
  --queue-url https://sqs.us-east-1.amazonaws.com/123456789012/orders \
  --attributes '{"RedrivePolicy":"{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:123456789012:orders-dlq\",\"maxReceiveCount\":\"5\"}"}'

aws lambda update-event-source-mapping \
  --uuid a1b2c3d4-5678-90ab-cdef-11111EXAMPLE \
  --function-response-types ReportBatchItemFailures

```

On **Service Bus**, set the threshold and enable dead-lettering on expiry, then fix the handler so a failure is a failure: let the exception escape or dead-letter explicitly. If handlers legitimately run longer than the lock, raise `maxAutoLockRenewalDuration` in the Functions `host.json` rather than the delivery count.

```bash
az servicebus queue update \
  --resource-group rg-orders --namespace-name sb-orders --name orders \
  --max-delivery-count 5 \
  --enable-dead-lettering-on-message-expiration true

```

On **Pub/Sub**, grant the service agent both roles, give the dead-letter topic a subscription, then set the policy. Order matters: a policy set before the grants starts forwarding nothing until they land.

```bash
gcloud pubsub topics add-iam-policy-binding orders-dead-letter \
  --member="serviceAccount:service-123456789012@gcp-sa-pubsub.iam.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

gcloud pubsub subscriptions add-iam-policy-binding orders-sub \
  --member="serviceAccount:service-123456789012@gcp-sa-pubsub.iam.gserviceaccount.com" \
  --role="roles/pubsub.subscriber"

gcloud pubsub subscriptions create orders-dead-letter-sub --topic=orders-dead-letter

gcloud pubsub subscriptions update orders-sub \
  --dead-letter-topic=orders-dead-letter \
  --max-delivery-attempts=5

```

Then give each dead-letter destination an alert routed to an owner. A dead-letter queue without an alarm is delayed data loss.

![Three lanes showing the repaired path on each provider: orders to orders-dlq after five receives with a CloudWatch alarm on visible messages, a Service Bus queue to its dead-letter subqueue after five deliveries with an Azure Monitor alert on DeadletteredMessages, and a Pub/Sub subscription to a dead-letter topic and subscription after five attempts with a Cloud Monitoring alert on dead_letter_message_count.](https://shakeride.com/guides/content/images/2026/11/sqs-dead-letter-queue-not-working-deep-dive-dlq-fixed-paths.svg)

```bash
# AWS: alarm when the dead-letter queue holds anything
aws cloudwatch put-metric-alarm --alarm-name orders-dlq-visible \
  --namespace AWS/SQS --metric-name ApproximateNumberOfMessagesVisible \
  --dimensions Name=QueueName,Value=orders-dlq \
  --statistic Maximum --period 300 --evaluation-periods 1 \
  --threshold 0 --comparison-operator GreaterThanThreshold \
  --alarm-actions arn:aws:sns:us-east-1:123456789012:orders-oncall

# Azure: alert on the namespace metric, filtered to the queue
az monitor metrics alert create --name orders-dead-lettered --resource-group rg-orders \
  --scopes /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-orders/providers/Microsoft.ServiceBus/namespaces/sb-orders \
  --condition "avg DeadletteredMessages > 0 where EntityName includes orders" \
  --window-size 5m --evaluation-frequency 5m

```

On Google Cloud, create a Cloud Monitoring alerting policy on `pubsub.googleapis.com/subscription/dead_letter_message_count` for `orders-sub`, and a second one on `subscription/oldest_unacked_message_age` for `orders-dead-letter-sub`, so a message left in the dead-letter subscription keeps paging until someone handles it.

## Verify with a controlled failing message

After configuration propagates, send a test message whose identifier is safe to follow and whose handler path is designed to fail in a sandbox. Observe deliveries, consumer logs and the dead-letter count. Do not use a production message or receive it by hand: on SQS a manual receive increments the receive count, and on Service Bus a peek-lock receive you do not settle counts as a delivery.

Verification is complete when the source configuration still names the intended target, the test message crosses the threshold, the target count increases, the alert fires and healthy messages continue to complete. Re-run the inspection commands rather than trusting a successful update response. Then fix the underlying consumer defect before redriving anything.

Redrive differs per provider. SQS has a native move task, `aws sqs start-message-move-task --source-arn arn:aws:sqs:us-east-1:123456789012:orders-dlq`, which returns messages to their original source queue. Service Bus has no move API: receive from the dead-letter subqueue and send again, from code or from Service Bus Explorer. Pub/Sub has none either: a small job pulls from `orders-dead-letter-sub`, republishes to the source topic and acknowledges. A dead-letter queue preserves evidence and bounds retries; it is not a successful processing destination.

## Avoid the traps that make messages look lost

Document how to inspect a message without exposing sensitive bodies and how to decide whether it is safe to replay. Redrive only after the consumer fix is deployed and capacity can handle the returning load.

- Do not confuse Lambda asynchronous destinations with an SQS source queue's `RedrivePolicy`.
- Do not lower retention during an incident without checking the age of existing messages.
- Do not assume an empty dead-letter queue proves successful processing: on SQS the source may not be receiving, on Service Bus expired messages may be dropped, on Pub/Sub the service agent may be unable to forward.
- Do not catch an exception and report success to the broker. Deleting, completing or answering 200 all acknowledge the poison message.
- Do not enable partial batch response until the function returns the required failed item identifiers.
- Do not replay poison messages until the cause is fixed and processing is idempotent: all three brokers deliver at least once.

## Practise on a live incident

These Shakeride challenges reproduce the failures above in a sandbox account, with the clock running:

- [Bad messages with nowhere to go](https://shakeride.com/challenges/bad-messages-with-nowhere-to-go?ref=shakeride.com): malformed messages disappear after a few retries. Runs on SQS, Service Bus and Pub/Sub.
- [Orders stop mid-pipeline](https://shakeride.com/challenges/orders-stop-mid-pipeline?ref=shakeride.com): a forwarding consumer keeps running while nothing moves on. Runs on all three clouds.
- [Accepted orders never reach the consumer](https://shakeride.com/challenges/accepted-orders-never-reach-the-consumer?ref=shakeride.com): every message is accepted and none arrives, without an error.
- [The same order is processed twice](https://shakeride.com/challenges/the-same-order-processed-twice?ref=shakeride.com): what at-least-once delivery does to a handler that is not idempotent.
- [Failed deliveries leave no trace](https://shakeride.com/challenges/failed-deliveries-leave-no-trace?ref=shakeride.com): the event delivery equivalent, on EventBridge, Event Grid and Pub/Sub.