Nov 18, 20266 min read

Google Pub/Sub Exactly-Once Delivery: What It Guarantees and What It Does Not

What exactly-once delivery on a Pub/Sub subscription actually promises, why it only works with pull subscriptions in one region, how to acknowledge with a response, and why your handlers still need to be idempotent.

Illustration for Google Pub/Sub Exactly-Once Delivery: What It Guarantees and What It Does Not

Exactly-once delivery is a checkbox on a Google Cloud Pub/Sub subscription, and what it gives you is narrower than the name: no redelivery after a successful acknowledgment, a way to know whether the acknowledgment worked, and only within one region on a pull subscription.

Teams that turn it on and drop their idempotency check find out the difference when a publisher retry or a crashed worker produces a second side effect.

This guide covers the exact guarantee, the conditions it depends on, the acknowledgment code, the costs in latency and quota, and the idempotency pattern you still need on top.

Exactly-once delivery at a glance

Encore exactly-once topicPub/Sub exactly-once subscriptionPub/Sub default subscription
Redelivery after a successful ackMinimized by the provider; handlers stay idempotentDoes not happenCan happen
Publish-side duplicatesNot deduplicatedStill deliveredStill delivered
Subscription typeDeclared in codePull and StreamingPull onlyPull or push
RegionProvisioned for youGuarantee holds within one regionNot applicable
Ack resultHandled by the runtimeackWithResponse tells you if it workedFire and forget
ThroughputProvider limits listed in the docsLower, with extra quotas and latencyHighest

What Pub/Sub guarantees

Per the exactly-once delivery docs, an exactly-once subscription promises that subscribers can tell whether an acknowledgment succeeded, that no redelivery happens after a successful acknowledgment, and that no redelivery happens while a message is outstanding (before its acknowledgment deadline expires). If a message is redelivered because the deadline expired or the client sent a negative acknowledgment, only the latest acknowledgment ID is valid, and acknowledging with an older one fails with INVALID_ARGUMENT.

The guarantee is keyed on the Pub/Sub message ID and holds within one region. A subscriber fleet spread across regions can receive duplicates even with the feature on, so run consumers in one region or use a locational endpoint.

What it does not cover

Two kinds of duplicates remain, and the first is on the publish side: if the publisher retries after a timeout, or Pub/Sub itself stores a publish twice, the subscription receives two messages, sometimes with different message IDs, and exactly-once cannot tell them apart. The second is your own handler: if it writes to the database and then crashes or loses the acknowledgment, the message comes back, and the write happens again unless you check for it.

The feature also only works on pull subscriptions: push and export subscriptions do not support it, which matters for Cloud Run services that receive messages over HTTP. The Pub/Sub emulator does not list exactly-once among its supported features either, so test it against a real subscription.

Turn it on and acknowledge with a response

Create the subscription with the flag, or set enableExactlyOnceDelivery from the client library:

~
$ gcloud pubsub subscriptions create invoice-worker \ --topic=invoice-requested \ --enable-exactly-once-delivery \ --ack-deadline=60

In the subscriber, use ackWithResponse() and treat a failed acknowledgment as "this message will come back":

import { PubSub, Message, Duration } from "@google-cloud/pubsub"; import { Pool } from "pg"; const pool = new Pool(); const sub = new PubSub().subscription("invoice-worker", { minAckDeadline: Duration.from({ seconds: 60 }), }); sub.on("message", async (msg: Message) => { const { invoiceId, customerId } = JSON.parse(msg.data.toString()); const client = await pool.connect(); try { // Idempotency: the marker row and the invoice commit together, or not at all. await client.query("BEGIN"); const res = await client.query( "INSERT INTO issued_invoices (invoice_id) VALUES ($1) ON CONFLICT DO NOTHING", [invoiceId], ); if (res.rowCount === 1) { await client.query( "INSERT INTO invoices (id, customer_id, status) VALUES ($1, $2, 'issued')", [invoiceId, customerId], ); } await client.query("COMMIT"); } catch (err) { await client.query("ROLLBACK"); msg.nack(); return; } finally { client.release(); } try { await msg.ackWithResponse(); } catch (err) { // The ack did not land; expect a redelivery, which the marker row absorbs. console.warn("ack failed", msg.id, err); } });

Google recommends a recent client library (Node v3.2.0 or higher) and a high minimum lease extension, up to 600 seconds, so network blips do not expire acknowledgment IDs. Without an explicit acknowledgment deadline, exactly-once subscriptions default to 60 seconds.

Costs: latency, throughput and quotas

Exactly-once subscriptions have noticeably higher publish-to-subscribe latency than regular ones, and they have extra regional quotas on messages consumed and acknowledged. With ordering also enabled, acknowledgments must arrive in order, and Google notes client throughput is then limited to the order of thousands of messages per second. For high throughput, use StreamingPull. If your handler already has a reliable idempotency check, the default at-least-once subscription with that check is often the better trade.

Exactly-once topics in Encore

Encore

Encore brings infrastructure from code to the topic and its subscribers, and the delivery guarantee is a field on the topic declaration. Setting deliveryGuarantee: "exactly-once" asks the cloud provider for its stronger delivery mode, and the Pub/Sub docs list the limits that come with it: 300 messages per second per topic on AWS, where the runtime publishes to an SNS FIFO topic with a deduplication ID, and at least 3,000 messages per second per region on GCP. On deploy to your own GCP project Encore provisions the Pub/Sub topic and subscriptions with dead-lettering, and provisions an IAM role for the service, or a service account on GCP.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

// billing/invoices.ts import { Topic, Subscription } from "encore.dev/pubsub"; import { SQLDatabase } from "encore.dev/storage/sqldb"; const db = new SQLDatabase("billing", { migrations: "./migrations" }); export interface InvoiceRequested { invoiceId: string; customerId: string; } export const invoiceRequested = new Topic<InvoiceRequested>("invoice-requested", { deliveryGuarantee: "exactly-once", }); const _ = new Subscription(invoiceRequested, "issue-invoice", { handler: async ({ invoiceId, customerId }) => { await using tx = await db.begin(); const row = await tx.queryRow<{ invoice_id: string }>` INSERT INTO issued_invoices (invoice_id) VALUES (${invoiceId}) ON CONFLICT DO NOTHING RETURNING invoice_id`; if (row) { await tx.exec` INSERT INTO invoices (id, customer_id, status) VALUES (${invoiceId}, ${customerId}, 'issued')`; } await tx.commit(); // a redelivery finds the marker row and writes nothing }, });

Encore's docs are explicit that exactly-once delivery does not deduplicate on the publish side, so publishing the same event twice delivers it twice, and they still recommend idempotent handlers where correctness matters. The handler above does both: it uses the stronger delivery mode to cut redeliveries, and a marker row committed in the same database transaction as the invoice makes the remaining ones harmless. Under encore run the topic runs in memory, so you can call the publishing endpoint and see the subscriber in the local trace.

A coding agent working in this repository can switch a topic between at-least-once and exactly-once with one field and keep the handler's idempotency check in the same diff.

Best fit: TypeScript or Go services on GCP or AWS that want fewer redeliveries on a low-volume, high-value topic, such as invoices or payouts, with the idempotency check kept in the handler.

Should you turn it on?

Turn it on for low-volume subscriptions where a duplicate is expensive and the subscriber already runs as a pull consumer in one region. Keep at-least-once with an idempotency key for high-volume topics, push subscriptions on Cloud Run, and anything that crosses regions. In both cases, the idempotency check is what makes the side effect happen once; exactly-once delivery only makes the check fire less often.

Frequently asked questions

Does Pub/Sub exactly-once delivery mean my handler runs once?

No. It means Pub/Sub does not redeliver a message after a successful acknowledgment or while it is outstanding, and it tells the subscriber whether the acknowledgment succeeded. A handler that finishes its work and then fails to acknowledge will see the message again, and publish-side retries can create duplicates with different message IDs. Handlers still need an idempotency check.

Can I use exactly-once delivery with push subscriptions?

No. Google only supports exactly-once delivery on pull subscriptions, including StreamingPull. Push and export subscriptions do not support it, because a push endpoint cannot confirm that Pub/Sub received its acknowledgment.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders