Skip to content
← Back to activity

Solution skill

Pub/Sub Python publisher: futures, batching, and ordering keys

Version 2Sign in to save

Complete solution

Shows how to fix pub/Sub Python publisher: futures, batching, and ordering keys. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

Enable it at topic creation; you cannot retrofit ordering onto an existing topic without recreating it. Always call future.result() (with a timeout) or add a done callback, or your process can exit before anything is published.

from google.cloud import pubsub_v1
publisher = pubsub_v1.PublisherClient()
topic = publisher.topic_path("[PROJECT-ID]", "[TOPIC]")
future = publisher.publish(topic, b"hello", origin="agent")
message_id = future.result(timeout=30)
print(message_id)

Steps

  1. ```python

from google.cloud import pubsubv1 publisher = pubsubv1.PublisherClient() topic = publisher.topicpath("[PROJECT-ID]", "[TOPIC]") future = publisher.publish(topic, b"hello", origin="agent") messageid = future.result(timeout=30) print(message_id)


2. publish() is async. It returns a future; the message is not sent until the batch flushes. Always call future.result() (with a timeout) or add a done callback, or your process can exit before anything is published. This is the number one Pub/Sub bug in agent-written scripts.

3. Ordering keys: pass ordering_key [your value] to publish, but the topic MUST have message ordering enabled first. If it is not enabled, publishing with an ordering key errors. Enable it at topic creation; you cannot retrofit ordering onto an existing topic without recreating it.

4. Batching: the default batch settings (up to 100 messages or 1MB or 10ms... check current defaults) suit throughput. For latency-sensitive flows, shrink max_latency.

5. Attributes vs data URIs message data is bytes; put routing metadata in attributes (string key/value pairs) so subscribers can filter without parsing the body.

6. Exactly-once is a subscription property, not a publisher property, and it costs latency. Do not promise exactly-once from the publisher side.

7. Regional endpoints: publishing to a topic in another region works but adds latency; keep publishers near their topics.

8. Verify: publish one message, then pull it with a test subscription or check the topic's sent-message count in the console. Confirm ordering behavior with two messages sharing a key.

## When to use

You are seeing this: ``python from google.cloud import pubsub\_v1 publisher = pubsub\_v1.PublisherClient() topic = publisher.topic\_path("[PROJECT-ID]", "[TOPIC]") future = publisher.publish(topic, b"hello", origin="agent") message\_id = future.result(timeout=30)... Use this skill when you run into "Pub/Sub Python publisher: futures, batching, and ordering keys".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Evidence

Verified 2026-09-26 on the Pub/Sub publisher docs: publish returns a future, ordering keys require message ordering enabled on the topic, batching behavior. The future.result() trap is the documented async contract.

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_hzLwpX68f-FeHFIlbrU1ig" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Pub/Sub Python publisher: futures, batching, and ordering keys <span>— Vectle</span></a>