Dead Letter Topics

In any messaging system, some messages inevitably fail processing. A subscriber might crash, the message might contain invalid data, or a downstream service might be permanently unavailable. Without a mechanism to handle these failures, problematic messages are redelivered indefinitely — blocking the subscription and wasting resources. Google Cloud Pub/Sub solves this with dead-letter topics (also called dead-letter queues).

---

What Is a Dead-Letter Topic?

A dead-letter topic is a regular Pub/Sub topic that receives messages that could not be successfully processed by a subscription after a configured number of delivery attempts. When a message exceeds the maximum delivery attempt threshold, Pub/Sub automatically forwards it to the dead-letter topic instead of continuing to redeliver it.

Why Dead-Letter Topics Matter

Problem	Without Dead-Letter Topic	With Dead-Letter Topic
Poison messages	Block the subscription indefinitely	Moved aside after max attempts
Processing errors	Continuous redelivery wastes resources	Failed messages isolated for inspection
Subscriber health	Healthy messages delayed behind failures	Subscription processes normally
Debugging	Hard to identify which messages failed	Failed messages collected in one place

---

Configuring Dead-Letter Topics

Step 1: Create the Dead-Letter Topic and Subscription

# Create the dead-letter topic
gcloud pubsub topics create orders-dead-letter

# Create a subscription on the dead-letter topic for monitoring
gcloud pubsub subscriptions create orders-dead-letter-sub \
  --topic=orders-dead-letter

Step 2: Configure the Source Subscription

# Create or update the subscription with dead-letter settings
gcloud pubsub subscriptions create orders-sub \
  --topic=orders-topic \
  --dead-letter-topic=orders-dead-letter \
  --max-delivery-attempts=5

Step 3: Grant Permissions

Pub/Sub needs permission to publish to the dead-letter topic and acknowledge messages on the source subscription:

# Get the Pub/Sub service account for your project
PROJECT_NUMBER=$(gcloud projects describe my-project --format="value(projectNumber)")
PUBSUB_SA="service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com"

# Grant publisher role on the dead-letter topic
gcloud pubsub topics add-iam-policy-binding orders-dead-letter \
  --member="serviceAccount:${PUBSUB_SA}" \
  --role="roles/pubsub.publisher"

# Grant subscriber role on the source subscription
gcloud pubsub subscriptions add-iam-policy-binding orders-sub \
  --member="serviceAccount:${PUBSUB_SA}" \
  --role="roles/pubsub.subscriber"

---

How Dead-Lettering Works

1. A message is published to orders-topic
2. Pub/Sub delivers the message to orders-sub
3. The subscriber fails to acknowledge (nacks or times out)
4. Pub/Sub redelivers the message (attempt 2)
5. After reaching the maximum delivery attempts (e.g., 5), Pub/Sub:
   • Publishes the message to orders-dead-letter
   • Acknowledges the message on orders-sub (removing it from the backlog)
6. The dead-letter subscription receives the failed message for inspection

Delivery Attempt Tracking

Pub/Sub tracks the delivery attempt count for each message. You can access this information in the message metadata:

def callback(message):
    delivery_attempt = message.delivery_attempt
    print(f"Delivery attempt: {delivery_attempt}")

    try:
        process(message)
        message.ack()
    except Exception as e:
        print(f"Processing failed (attempt {delivery_attempt}): {e}")
        message.nack()  # Redeliver or dead-letter

Dead-Letter Message Attributes

When a message is forwarded to the dead-letter topic, Pub/Sub adds metadata attributes: