Handle Failed Cloud Functions Events with Dead Letter Topics (2026)

A Cloud Function failing to execute is often a symptom of a much larger problem, not the problem itself.

Let’s watch a GCP Pub/Sub message get processed by a Cloud Function.

// Pub/Sub Message Payload
{
  "message": {
    "data": "eyAidXNlcklEIjogIjEyMzQ1IiwgImFjdGlvbiI6ICJjcmVhdGUifQ==", // Base64 encoded: {"userId": "12345", "action": "create"}
    "messageId": "1234567890",
    "publishTime": "2023-10-27T10:00:00.000Z",
    "attributes": {
      "eventType": "user_event"
    }
  },
  "subscription": "projects/my-project/subscriptions/my-subscription"
}

Our Cloud Function is triggered by my-subscription. It receives the Pub/Sub message, decodes the data field, and attempts to perform an action based on userId and action.

// Cloud Function (Node.js)
exports.processUserEvent = (message, context) => {
  const pubsubMessage = message.data;
  const decodedData = Buffer.from(pubsubData, 'base64').toString();
  const eventData = JSON.parse(decodedData);

  console.log(`Processing event for user: ${eventData.userId}, action: ${eventData.action}`);

  // Simulate a failure
  if (eventData.action === 'create' && eventData.userId === '12345') {
    throw new Error('Simulated failure: User creation failed for 12345');
  }

  // ... actual processing logic ...
};

If this function throws an error, Pub/Sub by default will retry delivering the message. This is usually good, but what happens if the function consistently fails for the same message? It might be stuck in a retry loop, consuming resources and potentially masking other issues. This is where a Dead Letter Topic (DLT) comes in.

A DLT is a separate Pub/Sub topic where messages that have failed to be processed after a configured number of retries are sent. This effectively "quarantines" problematic messages, preventing them from endlessly looping and allowing you to inspect them later.

To set this up, you first need a DLT topic. Let’s call it my-failed-events-dlt.

gcloud pubsub topics create my-failed-events-dlt

Next, you configure your existing subscription (my-subscription) to use this DLT. This is done by creating or updating the subscription’s message retention policy.

gcloud pubsub subscriptions update my-subscription \
  --dead-letter-topic=projects/my-project/topics/my-failed-events-dlt \
  --message-retention-duration=10m \
  --ack-deadline=60s \
  --max-delivery-attempts=5

Here’s what these parameters mean for the DLT behavior:

• --dead-letter-topic: This is the destination topic for messages that fail.
• --message-retention-duration: Although not directly tied to the DLT trigger, it’s good practice to set a reasonable retention for your main subscription. Messages are retained here until acknowledged or sent to the DLT. If the DLT isn’t configured, messages would eventually be dropped after their retry limit if enable-message-ordering is off or if they fail enough times that the retention period expires.
• --ack-deadline: This is the time Pub/Sub waits for an acknowledgment after delivering a message. If the function doesn’t acknowledge within this period (e.g., it crashes or throws an unhandled exception), the message is redelivered. A common value is 60s.
• --max-delivery-attempts: This is the crucial setting for DLTs. It defines how many times Pub/Sub will attempt to deliver a message to the subscriber (your Cloud Function) before sending it to the dead-letter topic. We’ve set it to 5 here. After the 5th delivery attempt fails (i.e., the function throws an error and doesn’t acknowledge), the message is sent to my-failed-events-dlt.

Once a message lands in my-failed-events-dlt, it stays there. You can then set up another process to consume from this DLT topic, inspect the messages, and decide what to do: reprocess them manually, discard them, or trigger an alert.

To inspect messages in the DLT, you can use gcloud pubsub subscriptions create to create a new subscription to the DLT topic and then gcloud pubsub messages pull.

# Create a subscription to the DLT topic for inspection
gcloud pubsub subscriptions create my-dlt-inspector-sub \
  --topic=my-failed-events-dlt \
  --ack-deadline=60s

# Pull messages from the inspector subscription
gcloud pubsub messages pull my-dlt-inspector-sub --auto-ack --limit=5

The auto-ack here is for demonstration; in a real inspection scenario, you’d want to pull, inspect, and then manually acknowledge or requeue.

When a message is sent to the DLT, Pub/Sub adds two attributes to it: gcp-pubsub-dead-lettering-reason and gcp-pubsub-dead-lettering-delivery-attempt. These provide context on why it was dead-lettered.

The most overlooked aspect of DLTs is that the max-delivery-attempts is a per-subscription setting. If you have multiple subscriptions to the same topic, each can have its own DLT configuration (or none at all), and message delivery attempts are counted independently for each subscription. This means a message might be dead-lettered on one subscription but still be delivered to another.

The next thing you’ll likely encounter is needing to reprocess messages from the DLT.