pubsub/WARN/2026_001

Active Pub/Sub subscriptions should have a Dead-Letter Queue configured.

Product: Cloud Pub/Sub
Rule class: WARN - Something that is possibly wrong

Description

Active Pub/Sub subscriptions should have a Dead-Letter Queue (DLQ) configured to prevent head-of-line delivery delays and runaway storage billing costs caused by unacknowledged poison messages. If a message cannot be processed successfully, the standard Pub/Sub behavior is to continuously redeliver it. Without a DLQ, these continuously failing messages will block subsequent healthy messages. Furthermore, because these messages remain unacknowledged, they pile up in the subscription’s backlog until they naturally expire, which accrues significant and unnecessary Pub/Sub message storage costs.

Remediation

Configure a Dead-Letter Queue (DLQ) for the active subscription:

  1. Create a dead-letter topic if one does not exist.
  2. Update the subscription’s Dead-Letter Policy to point to the dead-letter topic.
  3. Grant the Pub/Sub service account (service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com) the Publisher role on the dead-letter topic and the Subscriber role on the subscription.

For detailed steps, see Configuring dead-letter topics.

Further information