Stay organized with collections
Save and categorize content based on your preferences.
Use the gcpdiag tool to discover and fix potential
delivery issues for pull subscriptions.
Use the gcpdiag tool
gcpdiag
is an open source tool. It is not an officially supported Google Cloud product.
You can use the gcpdiag tool to help you identify and fix Google Cloud
project issues. For more information, see the
gcpdiag project on GitHub.
The gcpdiag tool helps you discover Pub/Sub
pull delivery issues by performing the following checks:
Quota errors: Evaluates Logs Explorer logs to check for any quota errors in
regions and zones.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Troubleshoot pull delivery issues\n\n\u003cbr /\u003e\n\nUse the `gcpdiag` tool to discover and fix potential\ndelivery issues for pull subscriptions.\n\nUse the `gcpdiag` tool\n----------------------\n\n[`gcpdiag`](https://gcpdiag.dev)\nis an open source tool. It is not an officially supported Google Cloud product.\nYou can use the `gcpdiag` tool to help you identify and fix Google Cloud\nproject issues. For more information, see the\n[gcpdiag project on GitHub](https://github.com/GoogleCloudPlatform/gcpdiag/#gcpdiag---diagnostics-for-google-cloud-platform). \nThe `gcpdiag` tool helps you discover Pub/Sub\npull delivery issues by performing the following checks:\n\n- **Quota errors:** Evaluates Logs Explorer logs to check for any quota errors in regions and zones.\n- **Throughput qualification:** Performs checks on the [delivery latency health](/pubsub/docs/monitoring#delivery_latency_health) of a subscription.\n\nFor a list of `gcpdiag` pull delivery evaluation steps, see\n[Potential steps](https://gcpdiag.dev/runbook/diagnostic-trees/pubsub/pull-subscription-delivery/#potential-steps).\n\n### Run the `gcpdiag` command\n\nYou can run the `gcpdiag` command from Google Cloud CLI or within\na [Docker](https://www.docker.com/) container.\n\nGoogle Cloud console\n--------------------\n\n1. Complete and then copy the following command. \n\n gcpdiag runbook pubsub/pull-subscription-delivery \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --parameter subscription_name=\u003cvar translate=\"no\"\u003eSUBSCRIPTION_NAME\u003c/var\u003e\n\n2. Open the Google Cloud console and activate Cloud Shell.\n[Open Cloud console](https://console.cloud.google.com/cloudpubsub/topic/list?cloudshell=true ?cloudshell=true)\n3. Paste the copied command.\n4. Run the `gcpdiag` command, which downloads the `gcpdiag` docker image, and then performs diagnostic checks. If applicable, follow the output instructions to fix failed checks.\n\nDocker\n------\n\nYou can [run `gcpdiag` using a wrapper](https://github.com/GoogleCloudPlatform/gcpdiag?tab=readme-ov-file#installation) that starts `gcpdiag` in a\n[Docker](https://www.docker.com/) container. Docker or\n[Podman](https://podman.io/) must be installed.\n\n1. Copy and run the following command on your local workstation. \n\n ```console\n curl https://gcpdiag.dev/gcpdiag.sh \u003egcpdiag && chmod +x gcpdiag\n ```\n2. Execute the `gcpdiag` command. \n\n ./gcpdiag runbook pubsub/pull-subscription-delivery \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --parameter subscription_name=\u003cvar translate=\"no\"\u003eSUBSCRIPTION_NAME\u003c/var\u003e\n\nView [available parameters](https://gcpdiag.dev/runbook/diagnostic-trees/pubsub/pull-subscription-delivery/#parameters) for this runbook.\n\nReplace the following:\n\n- \u003cvar class=\"readonly\" translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The ID of the project to evaluate\n- \u003cvar class=\"readonly\" translate=\"no\"\u003eSUBSCRIPTION_NAME\u003c/var\u003e: The name of the subscription to evaluate in your project\n\nUseful flags:\n\n- `--universe-domain`: If applicable, the [Trusted Partner Sovereign Cloud](https://cloud.google.com/blog/products/identity-security/new-sovereign-controls-for-gcp-via-assured-workloads) domain hosting the resource\n- `--parameter` or `-p`: Runbook parameters\n\nFor a list and description of all `gcpdiag` tool flags, see the\n[`gcpdiag` usage instructions](https://github.com/GoogleCloudPlatform/gcpdiag?tab=readme-ov-file#usage).\n\nRead related information\n------------------------\n\n- [Pub/Sub pull subscription common issues](/pubsub/docs/pull-troubleshooting)"]]