Messaging error catalogue

1. The consumer sees the same message twice


cause	not a bug. Standard Pub/Sub subscriptions are at-least-once
check	is exactly-once delivery enabled on this subscription? By default it is not
fix	make the consumer idempotent — the correct answer. Or enable exactly-once delivery, knowing you have changed the delivery semantics

This is the first row in the catalogue because it is the first thing a queue consumer ported from elsewhere gets wrong, and because "fix the duplicates" is the wrong framing.

2. A push subscription stops delivering


cause	push is an HTTP POST to your endpoint. If the endpoint does not return success, Pub/Sub retries
check	what is the endpoint returning? On Cloud Run look for 429 "The request was aborted because there was no available instance." and 503 "The request failed because the instance could not start successfully."
fix	a 429 is capacity: raise maximum instances, or switch to a pull subscription so the consumer sets its own pace. A 503 is configuration — usually a secret the runtime identity cannot read

A push subscription couples your delivery rate to your service's scaling. That is the trade: pull gives the consumer flow control, push gives you no consumer to run.

3. Messages disappeared


cause	no dead-letter topic, and the message exceeded the subscription's retention
check	does the subscription have a dead-letter topic? What is its retention set to?
fix	configure a dead-letter topic on every subscription whose consumer can fail. Without one, a permanently-failing message is retried until retention expires and is then gone with no record

Recorded as an absence: the Pub/Sub overview states no default retention value, so none is quoted here. Read it from the subscription before relying on a replay window.

4. Throughput collapsed after enabling ordering


cause	ordering keys serialise delivery per key
check	how many distinct keys are in use? If the answer is "one", every message is in one queue
fix	choose a key with high cardinality, or drop ordering where the consumer does not need it. Pub/Sub's native model is per-message parallelism "unlike partition-based systems" — ordering is the thing that gives that up

This is the row a Kafka migration meets: a partition count became an ordering key, and a low-cardinality key is a one-partition topic.

5. Tasks dispatch too slowly, or all at once


cause	a Cloud Tasks queue carries the rate limits and the retry parameters — all tasks in it share them
check	which queue is this task in, and what are that queue's rate limits?
fix	separate queues for separate policies. A queue is a policy, not a container

6. An Eventarc trigger never fires


cause	usually the source, not the destination: the event you expect is not published directly and must come through Cloud Audit Logs — which means the relevant audit log type has to be enabled
check	is this source a direct publisher or an audit-log-derived event? Is that audit log type on for the resource?
fix	enable the audit log type, or re-target the trigger at a source that publishes directly

And one shape error: a trigger that needs the message transformed is an Eventarc Advanced design (bus plus pipelines), not a Standard trigger with extra configuration.

Next: guides/messaging/deliver-pubsub-to-cloud-run.md, guides/parity/messaging.md.