How to Use Dead Letter Topic in Google Cloud Pub/Sub

In Google Cloud Pub/Sub, use a deadLetterPolicy on a subscription to send undeliverable messages to a dead letter topic. This helps isolate and inspect messages that fail delivery after a set number of attempts.

Syntax

To use a dead letter topic in Pub/Sub, you configure a subscription with a deadLetterPolicy. This policy includes the deadLetterTopic and maxDeliveryAttempts. The deadLetterTopic is where failed messages are sent after retry attempts exceed maxDeliveryAttempts.

Example parts:

• deadLetterTopic: Full resource name of the dead letter topic.
• maxDeliveryAttempts: Number of delivery tries before sending to dead letter topic.

python

subscription = pubsub_v1.types.Subscription(
    name="projects/your-project/subscriptions/your-subscription",
    topic="projects/your-project/topics/your-topic",
    dead_letter_policy=pubsub_v1.types.DeadLetterPolicy(
        dead_letter_topic="projects/your-project/topics/your-dead-letter-topic",
        max_delivery_attempts=5
    )
)

Example

This example shows how to create a Pub/Sub subscription with a dead letter topic using Python. Messages that fail delivery 5 times are sent to the dead letter topic for later inspection.

python

from google.cloud import pubsub_v1

project_id = "your-project"
topic_id = "your-topic"
dead_letter_topic_id = "your-dead-letter-topic"
subscription_id = "your-subscription"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()

# Full resource names
topic_path = publisher.topic_path(project_id, topic_id)
dead_letter_topic_path = publisher.topic_path(project_id, dead_letter_topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

# Create dead letter topic if it doesn't exist
try:
    publisher.get_topic(request={"topic": dead_letter_topic_path})
except Exception:
    publisher.create_topic(request={"name": dead_letter_topic_path})

# Create subscription with dead letter policy
dead_letter_policy = pubsub_v1.types.DeadLetterPolicy(
    dead_letter_topic=dead_letter_topic_path,
    max_delivery_attempts=5
)

subscription = pubsub_v1.types.Subscription(
    name=subscription_path,
    topic=topic_path,
    dead_letter_policy=dead_letter_policy
)

try:
    subscriber.create_subscription(request={"subscription": subscription})
    print(f"Subscription created with dead letter topic: {dead_letter_topic_path}")
except Exception as e:
    print(f"Error creating subscription: {e}")

Output

Subscription created with dead letter topic: projects/your-project/topics/your-dead-letter-topic

Common Pitfalls

• Dead letter topic must exist before assigning it to a subscription. Creating a subscription with a non-existent dead letter topic causes errors.
• maxDeliveryAttempts must be between 5 and 100. Setting values outside this range is invalid.
• Dead letter topics cannot be the same as the subscription's main topic. This causes configuration errors.
• Permissions: The Pub/Sub service account needs pubsub.publisher role on the dead letter topic.

python

## Wrong: Dead letter topic does not exist
subscription = pubsub_v1.types.Subscription(
    name=subscription_path,
    topic=topic_path,
    dead_letter_policy=pubsub_v1.types.DeadLetterPolicy(
        dead_letter_topic="projects/your-project/topics/non-existent-topic",
        max_delivery_attempts=5
    )
)

# This will raise an error because dead letter topic is missing

## Right: Create dead letter topic first
publisher.create_topic(request={"name": dead_letter_topic_path})

subscription.dead_letter_policy.dead_letter_topic = dead_letter_topic_path

# Now create subscription succeeds

Quick Reference

• Dead letter topic must be a Pub/Sub topic in the same project.
• Set maxDeliveryAttempts between 5 and 100.
• Grant Pub/Sub service account pubsub.publisher role on dead letter topic.
• Use dead letter topics to isolate and debug undeliverable messages.

Key Takeaways

Configure a dead letter topic in your subscription's deadLetterPolicy to handle undeliverable messages.

Ensure the dead letter topic exists before assigning it to a subscription.

Set maxDeliveryAttempts between 5 and 100 to control retry attempts before dead lettering.

Grant Pub/Sub service account publisher permissions on the dead letter topic.

Use dead letter topics to isolate and troubleshoot messages that fail delivery.