Dead-letter topics

Subscribers might not be able to handle messages for a variety of reasons. For example, there could be transient issues retrieving data needed to process a message. Or, a message could be in a format that the subscriber does not expect.

To manage undeliverable messages that subscribers can't acknowledge, Pub/Sub can forward them to a dead-letter topic (also known as a dead-letter queue).

Before you begin

  • Create a topic for your dead-letter topic configuration.

    Or, if you follow all instructions on this page end-to-end, you can create the topic in a subsequent step.

Required roles

To get the permissions that you need to manage topics and subscriptions, ask your administrator to grant you the Pub/Sub Editor (roles/pubsub.editor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

You can configure access control at the project level and at the individual resource level. You can create a subscription in one project and attach it to a topic located in a different project. Ensure that you have the required permissions for each project.

How dead-letter topics work

When a subscriber application can't acknowledge a message, Pub/Sub retries delivery until the acknowledgment deadline is met or the message expires. After an approximately configured number of delivery attempts, Pub/Sub can forward the undeliverable message to a dead-letter topic.

When Pub/Sub forwards an undeliverable message, it wraps the original message in a new one and adds attributes that identify the source subscription. The message is then sent to the specified dead-letter topic. A separate subscription attached to the dead-letter topic can then receive these forwarded messages for analysis and offline debugging.

How maximum delivery attempts are calculated

Pub/Sub only counts delivery attempts when a dead-letter topic is configured correctly and includes the correct IAM permissions.

The maximum number of delivery attempts is approximate because Pub/Sub forwards undeliverable messages on a best-effort basis. The service might forward a message after fewer attempts than configured, or it might attempt delivery a few more times before forwarding.

The tracked number of delivery attempts for a message may also reset to zero, especially for a pull subscription with inactive subscribers. As a result, the messages might be delivered to the subscriber client more times than the configured maximum number of delivery attempts.

Dead-letter topic properties

You can set the following subscription properties on a dead-letter topic.

  • Maximum number of delivery attempts: A numeric value that signifies the number of delivery attempts that Pub/Sub makes for a specific message. If the subscriber client cannot acknowledge the message within the configured number of delivery attempts, the message is forwarded to a dead-letter topic.

    • Default value = 5
    • Maximum value = 100
    • Minimum value = 5

  • Project with the dead-letter topic: If the dead-letter topic is in a different project from the subscription, you must specify the project with the dead-letter topic. Set the dead-letter topic to a different topic from the topic to which the subscription is attached.

Configure a dead-letter topic

The following steps describe the workflow for using dead-letter topics.

  1. Create a topic (to use as a dead-letter topic).

  2. Create a subscription for your dead-letter topic.

  3. Enable Dead lettering on your subscription.

  4. Attach the topic you created earlier to your subscription.

  5. Grant the required roles to use dead-letter topics to your Pub/Sub service account.

Create a topic to use with dead-letter topics

If you already created a topic to use for your subscription, you can skip this step.

  1. In the Google Cloud console, go to the Topics page.

    Go to Topics

  2. Click Create topic.

  3. Enter a Topic ID, for example, my-test-topic.

  4. Retain the option for the default subscription and click Create.

Set a dead-letter topic on a subscription

You can set a dead-letter topic on a new subscription or an existing subscription.

Set a dead-letter topic on a new subscription

You can create a subscription and set a dead-letter topic using the Google Cloud console, the Google Cloud CLI, the client libraries, or the Pub/Sub API.

Console

To create a subscription and set a dead-letter topic, complete the following steps:

  1. In the Google Cloud console, go to the Subscriptions page.

    Go to Subscriptions

  2. Click Create subscription.

  3. Enter the Subscription ID.

  4. Choose the topic you want to use with your subscription. The subscription receives messages from the topic. This is not your dead-letter topic. You choose that in the next step.

  5. In the Dead lettering section, select Enable dead lettering.

  6. Choose a dead-letter topic from the drop-down menu.

    If the chosen dead-letter topic does not have a subscription, the system prompts you to create one.

  7. In the Maximum delivery attempts field, specify an integer between 5 and 100.

  8. Click Create.

  9. Click the Details panel to identify any possible action items. If any of the items show an error icon , click the action item to resolve the issue.

    The Dead Lettering tab with some action items.

gcloud

To create a subscription and set a dead-letter topic, use the gcloud pubsub subscriptions create command:

gcloud pubsub subscriptions create subscription-id \
  --topic=topic-id \
  --dead-letter-topic=dead-letter-topic-name \
  [--max-delivery-attempts=max-delivery-attempts] \
  [--dead-letter-topic-project=dead-letter-topic-project]

C++

Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation.