Updated Nov 20, 20266 min read

Google Cloud Pub/Sub Flow Control and Subscriber Concurrency

How flow control works in the Google Cloud Pub/Sub client libraries, what MaxOutstandingMessages and MaxOutstandingBytes limit, why push subscriptions behave differently, and how to cap concurrency for a handler that calls a rate-limited API.

Illustration for Google Cloud Pub/Sub Flow Control and Subscriber Concurrency

Google Cloud Pub/Sub delivers messages as fast as a subscriber accepts them, and the Go v2 client accepts 1,000 outstanding messages by default. That suits a handler writing to a database, and breaks one calling a geocoding API that allows five requests at a time.

Flow control is how a pull subscriber says how much it can take. This guide covers the settings, the backlog problem they do not solve and how push subscriptions differ.

What does flow control limit?

SettingGo v2 clientNode.jsPythonWhat it limits
MessagesReceiveSettings.MaxOutstandingMessages (1,000)flowControl.maxMessages (1,000)FlowControl(max_messages=...)Unacked messages held by the client
BytesReceiveSettings.MaxOutstandingBytes (1e9)flowControl.maxBytes (100 MB)FlowControl(max_bytes=...)Total size of those messages
StreamsReceiveSettings.NumGoroutines (1)streamingOptions.maxStreams (5)Set by the clientParallel StreamingPull connections
LeaseReceiveSettings.MaxExtension (60 minutes)maxExtensionTimeFlowControl(max_lease_duration=...)How long the client keeps extending a message's ack deadline

The Go defaults are from DefaultReceiveSettings in the v2 package, the Node.js defaults from the client's source, and the per-language examples are in Google's flow control guide. In the Go client, MaxOutstandingMessages also caps the number of handler callbacks running at once, so it doubles as a concurrency limit.

How does flow control work?

The client opens a StreamingPull stream and receives messages into a local buffer, and each message counts against the limits until the handler acks or nacks it. When either the message count or the byte total reaches its limit, the client stops asking for more, and while a message is outstanding the client keeps extending its ack deadline in the background, up to the lease limit. Flow control is per subscriber client, so three Cloud Run instances or GKE pods each running a subscriber with MaxOutstandingMessages = 100 can hold 300 messages between them.

A Go subscriber that processes at most 5 messages at a time:

sub := client.Subscriber("geocode-address") sub.ReceiveSettings.MaxOutstandingMessages = 5 sub.ReceiveSettings.MaxOutstandingBytes = 10 << 20 // 10 MiB err := sub.Receive(ctx, func(ctx context.Context, m *pubsub.Message) { if err := geocode(ctx, m.Data); err != nil { m.Nack() return } m.Ack() })

Why does a subscriber hold more messages than its limit?

Pub/Sub delivers messages to a streaming subscriber in batches, and the batch size cannot be configured, so a single batch can push a client past its limit. The Node.js client documents this in its flow control options: maxMessages defaults to 1,000 and maxBytes to 100 MB, and with allowExcessMessages left at its default of true the limit is very likely to be exceeded. Setting it to false makes the client hold the excess back until handlers are ready, which keeps those messages from being redelivered and makes maxMessages behave like the concurrency cap most people expect. In Go, MaxOutstandingMessages also sets how many callbacks run at once, and a subscriber that opens more than one stream with NumGoroutines should also turn on EnablePerStreamFlowControl, as the package docs recommend.

How do push subscriptions handle concurrency?

Push subscriptions have no client and no flow control settings. Pub/Sub sends each message as an HTTPS request and controls the rate with a push window, which starts at a small number of concurrent requests, grows while the endpoint acknowledges more than 99% of messages in under a second, and shrinks when requests fail or slow down, per the push subscription docs. For a Cloud Run endpoint, the effective limit on concurrent work is the service's maximum instances times its per-instance concurrency, and a 429 or 503 from the service counts as a failure that slows delivery and resends the message with backoff.

How do you set subscriber concurrency with Encore?

Encore brings infrastructure from code, and a subscription's concurrency, ack deadline and retry policy are declared next to the handler, with Encore creating the topic, the subscription and a dead-letter topic in your GCP project on deploy. The maxConcurrency option caps how many messages each instance of the service processes at once, the same job MaxOutstandingMessages does for a hand-written subscriber. Per the GCP infrastructure docs, services run on Cloud Run or GKE in your own project.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

A subscription in front of a geocoding provider that allows 5 requests in flight:

// geocode/geocode.ts import { api } from "encore.dev/api"; import { Topic, Subscription } from "encore.dev/pubsub"; import log from "encore.dev/log"; export interface AddressAdded { addressID: string; line: string; } export const addressAdded = new Topic<AddressAdded>("address-added", { deliveryGuarantee: "at-least-once", }); // Counters to see the limit at work while testing locally. let inFlight = 0; let peak = 0; const _ = new Subscription(addressAdded, "geocode-address", { // At most 5 handlers run at once on each instance of this service. maxConcurrency: 5, // Give each attempt a full minute before the message is redelivered. ackDeadline: "60s", retryPolicy: { minBackoff: "5s", maxBackoff: "5m", maxRetries: 8 }, handler: async (msg) => { inFlight++; peak = Math.max(peak, inFlight); try { await new Promise((r) => setTimeout(r, 300)); // stand-in for the provider call log.info("geocoded", { addressID: msg.addressID, inFlight, peak }); } finally { inFlight--; } }, }); export const importAddresses = api( { expose: true, method: "POST", path: "/addresses/import" }, async (p: { count: number }): Promise<{ published: number }> => { const n = Math.min(Math.max(p.count, 0), 500); await Promise.all( Array.from({ length: n }, (_, i) => addressAdded.publish({ addressID: `a${i}`, line: `${i} Main St` }), ), ); return { published: n }; }, ); export const stats = api( { expose: true, method: "GET", path: "/addresses/stats" }, async (): Promise<{ inFlight: number; peak: number }> => ({ inFlight, peak }), );

Run locally with encore run. A request that publishes 40 messages should end with GET /addresses/stats showing a peak of 5 handlers in flight and all 40 processed. The limit is per instance, so a service scaled to 4 instances can run 20 handlers at once, which matters when the provider's limit is per API key and not per instance. On Cloud Run, subscriptions to unordered topics are delivered as push requests, where Pub/Sub's push window sets the rate instead of maxConcurrency, as the SDK reference for maxConcurrency notes, so a strict global limit on Cloud Run belongs in the handler, for example a token bucket in Redis or a Postgres database. The retry policy and dead-letter behavior are covered in the Pub/Sub docs, and the GCP Pub/Sub import guide shows how to use an existing topic.

An agent changing the provider limit edits one number next to the handler, and the local run shows the effect in the trace view right away, with no subscriber client settings or Terraform for the subscription to keep in sync.

Best fit: Backends on GCP that want each subscription's concurrency, deadline and retries declared next to its handler, with the topic and dead-letter topic created in their own project.

How do you pick flow control values?

Start from the slowest dependency the handler calls: if it allows N requests in flight, set the per-instance limit to N divided by the maximum number of instances, and set the ack deadline above the handler's slowest normal run so a working message is not redelivered. Watch subscription/oldest_unacked_message_age in Cloud Monitoring: a value that keeps growing means the subscribers cannot keep up at the limits you set, and the answer is more instances or a faster handler, not a higher limit on each client.

Frequently asked questions

What does Pub/Sub flow control do?

Flow control limits how many messages, and how many bytes of messages, a subscriber client holds without acknowledging them. When either limit is reached, the client stops pulling new messages until handlers ack or nack enough of them, which keeps a slow subscriber from taking more than it can process.

What is the default MaxOutstandingMessages in the Go Pub/Sub client?

In the v2 Go client, the defaults are 1,000 outstanding messages and 1e9 bytes, with one StreamingPull stream per subscriber. MaxOutstandingMessages also sets the maximum number of handler callbacks running at the same time.

Does flow control apply to push subscriptions?

No. Flow control is a client library setting for pull subscribers. For push subscriptions, Pub/Sub adjusts the number of concurrent push requests with a slow-start window that grows while the endpoint acknowledges quickly and shrinks when requests fail or slow down.

How do I limit how many Pub/Sub messages a handler processes at once?

With Encore you set maxConcurrency on the subscription in application code, which caps how many messages each instance of the service processes at the same time. The setting lives in the subscription declaration, next to the handler it protects.

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