Google Pub/Sub with Bun: From Local Development to Production

Why Bun + Pub/Sub?

Google Pub/Sub seems simple: create a topic, publish, subscribe, done.

In reality—especially when layering Bun, Docker, and multiple authentication methods—there are sharp edges that can burn a day or two of debugging.

This post is experience-driven. It covers what actually happens, not what the docs say should happen.

The Case for Bun + Pub/Sub

Bun works exceptionally well with the official Google Cloud Node.js SDKs:

• No hacks or polyfills needed
• Async/await support is clean
• Performs well under load
• Startup time is fast (important for serverless)

Use Bun + Pub/Sub when building:

• Log pipelines
• Background workers
• Event-driven microservices
• Internal tooling
• Message brokers

If you’re doing any of this in GCP, Bun + Pub/Sub is a solid, pragmatic choice.

Part 1: Installation

Add the Dependency

bun add @google-cloud/pubsub

That’s it. No Bun-specific adapters. No polyfills. The official SDK just works.

Package Structure

1
{
2
  "dependencies": {
3
    "@google-cloud/pubsub": "^4.x.x"
4
  }
5
}

Version 4.x is stable and actively maintained. Use it.

Part 2: The Mental Model (Critical)

Before writing code, understand responsibility boundaries.

Golden Rule:

Runtime services should only publish and consume, never create or discover infrastructure.

This single rule avoids 90% of Pub/Sub pain.

Why This Matters

1
// Anti-pattern
2
await pubsub.topic('logs').get({ autoCreate: true });

This requires:

• pubsub.topics.get
• pubsub.topics.create
• Admin-level permissions

Your app shouldn’t need admin permissions.

1
// Correct pattern
2
const topic = pubsub.topic('logs');
3
// Publishing will fail clearly if topic doesn't exist
4
await topic.publishMessage({ json: { ... } });

If the topic doesn’t exist, publishing fails with a clear error. That’s intentional. Your infra team knows about it.

Part 3: Basic Publisher (Bun)

Simple Publish

1
import { PubSub } from '@google-cloud/pubsub';
2

3
const pubsub = new PubSub({
4
  projectId: process.env.GCP_PROJECT_ID,
5
});
6

7
const topic = pubsub.topic(process.env.PUBSUB_TOPIC_NAME!);
8

9
// Publish a message
10
await topic.publishMessage({
11
  json: { message: 'hello world', timestamp: Date.now() },
12
});
13

14
console.log('Message published');

If this fails, it will fail clearly—assuming authentication is set up correctly.

Publish with Attributes

1
await topic.publishMessage({
2
  json: { order_id: '12345', amount: 99.99 },
3
  attributes: {
4
    priority: 'high',
5
    source: 'checkout',
6
    attempt: '1',
7
  },
8
});

Attributes are key-value pairs for filtering and routing downstream.

Batch Publishing

1
const messages = [];
2

3
for (let i = 0; i < 1000; i++) {
4
  messages.push({
5
    json: { event: 'user_login', userId: `user_${i}` },
6
  });
7
}
8

9
await Promise.all(
10
  messages.map(msg => topic.publishMessage(msg))
11
);

Or let the client batch automatically:

1
const pubsub = new PubSub({
2
  projectId: process.env.GCP_PROJECT_ID,
3
  batching: {
4
    maxMilliseconds: 100,
5
    maxBytes: 10 * 1024 * 1024,
6
    maxMessages: 100,
7
  },
8
});

The client waits up to 100ms, accumulates up to 100 messages or 10MB, then sends a batch.

Error Handling

1
try {
2
  await topic.publishMessage({ json: { data: 'important' } });
3
} catch (error) {
4
  console.error('Failed to publish:', error.message);
5

6
  // Implement backoff/retry logic
7
  // Or send to a dead-letter topic
8
}

Part 4: Basic Subscriber (Bun)

Consume Messages

1
import { PubSub } from '@google-cloud/pubsub';
2

3
const pubsub = new PubSub({
4
  projectId: process.env.GCP_PROJECT_ID,
5
});
6

7
const subscription = pubsub.subscription(
8
  process.env.PUBSUB_SUBSCRIPTION_NAME!
9
);
10

11
// Listen for messages
12
subscription.on('message', (message) => {
13
  console.log('Received message:', message.data.toString());
14
  console.log('Attributes:', message.attributes);
15

16
  // Process the message
17
  // ...
18

19
  // Acknowledge after processing
20
  message.ack();
21
});
22

23
// Error handling
24
subscription.on('error', (error) => {
25
  console.error('Subscription error:', error);
26
});

Acknowledge vs Nack

1
subscription.on('message', (message) => {
2
  try {
3
    // Process message
4
    const data = JSON.parse(message.data.toString());
5
    processData(data);
6

7
    // Success: acknowledge
8
    message.ack();
9
  } catch (error) {
10
    // Failure: nack (message returns to queue)
11
    message.nack();
12
  }
13
});

If you nack(), the message returns to Pub/Sub and will be retried (delivered again).

Graceful Shutdown

1
subscription.on('message', (message) => {
2
  // Process...
3
  message.ack();
4
});
5

6
// When shutting down
7
process.on('SIGTERM', async () => {
8
  console.log('Shutting down...');
9
  subscription.close();
10
  await pubsub.close();
11
});

Part 5: Authentication — The Three Methods

This is where most pain lives. Understand all three.

Method 1: Application Default Credentials (ADC) — Recommended

ADC is how Google Cloud wants you to authenticate. No secrets in code.

Local Setup:

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

This creates:

1
~/.config/gcloud/application_default_credentials.json

Your Bun app picks it up automatically:

1
const pubsub = new PubSub({
2
  projectId: process.env.GCP_PROJECT_ID,
3
  // ADC is used automatically, no keyFilename needed
4
});

Advantages:

• No secrets in code
• Works locally and in production
• Easy credential rotation
• Same code everywhere

Disadvantages:

• Must configure locally (one-time)
• Docker requires special handling (more on that later)

Method 2: Service Account JSON File

Sometimes unavoidable (CI systems, legacy setups).

1
const pubsub = new PubSub({
2
  projectId: 'my-project',
3
  keyFilename: '/path/to/service-account.json',
4
});

Advantages:

• Works in constrained environments
• Explicit about which SA is used

Disadvantages:

• Secrets on disk (rotation pain)
• Easy to commit to git
• Docker complexity increases
• Production risk (stale keys)

When to use: Only if ADC is impossible.

Method 3: ADC via Environment Variable

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json

Still ADC, but file-backed.

1
const pubsub = new PubSub({
2
  projectId: process.env.GCP_PROJECT_ID,
3
  // Uses GOOGLE_APPLICATION_CREDENTIALS automatically
4
});

Good for: CI/CD, containers, when file path is dynamic.

Part 6: IAM Permissions (Minimum)

Over-permissioning is the fastest way to hide bugs.

For Publishers Only

1
roles/pubsub.publisher

That’s it. Nothing else.

For Subscribers Only

1
roles/pubsub.subscriber

For Both

1
- roles/pubsub.publisher
2
- roles/pubsub.subscriber

What You DO NOT Need

1
roles/pubsub.admin       # Way too much
2
roles/editor             # Way too much
3
roles/owner              # Way too much
4
pubsub.topics.get        # Unless discovering at runtime
5
pubsub.topics.create     # Unless creating at runtime

Assign only what’s needed. If your app crashes due to missing permissions, that’s good—it means your config is under-scoped, which is safer than over-scoped.

Part 7: The Infamous Error: “undefined undefined: undefined”

You’ll see this error eventually:

1
Error: undefined undefined: undefined

It’s cryptic. It’s useless. But it has a meaning.

What It Really Means

One of these:

1. Missing IAM permission (often pubsub.topics.get)
2. Calling topic.exists() or topic.get() with insufficient rights
3. Empty or undefined GCP_PROJECT_ID
4. Empty or undefined topic name
5. Topic doesn’t exist (and you’re trying to auto-create)

Why the Error Is So Bad

The Node.js gRPC client sometimes loses metadata during retries and surfaces this generic message. The actual error is swallowed.

How to Debug It

1
// Add logging
2
console.log('Project ID:', process.env.GCP_PROJECT_ID);
3
console.log('Topic name:', process.env.PUBSUB_TOPIC_NAME);
4

5
try {
6
  const topic = pubsub.topic(process.env.PUBSUB_TOPIC_NAME!);
7

8
  // Don't call exists() or get() — just publish
9
  await topic.publishMessage({ json: { test: true } });
10

11
  console.log('Success');
12
} catch (error) {
13
  console.error('Full error:', JSON.stringify(error, null, 2));
14
  console.error('Message:', error.message);
15
  console.error('Code:', error.code);
16
}

The error codes matter:

• PERMISSION_DENIED → IAM issue
• NOT_FOUND → Topic doesn’t exist
• UNAUTHENTICATED → Auth not set up
• INVALID_ARGUMENT → Bad project ID or topic name

Part 8: Docker — Where Things Break

Docker introduces two critical differences.

Problem 1: ADC Is Not Automatically Available

Your host machine having ADC does NOT mean your container does.

This fails:

docker run my-app

Your app can’t find the credentials.

Correct approach:

Mount the ADC credentials:

1
services:
2
  app:
3
    build: .
4
    volumes:
5
      - ~/.config/gcloud:/home/app/.config/gcloud:ro
6
    environment:
7
      HOME: /home/app
8
      GCP_PROJECT_ID: my-project
9
      PUBSUB_TOPIC_NAME: logs

Key points:

• Mount to /home/app/.config/gcloud (the app user’s home)
• Set HOME=/home/app so the client finds it
• Use :ro (read-only) for security

Problem 2: Non-root Users Matter

If your Dockerfile has:

1
USER app

Then ADC must live under /home/app/.config/gcloud, not /root/.config/gcloud.

If you mount to /root and the container runs as user app, the client won’t find it—and will silently fail.

Complete Docker Compose Example (Correct)

1
version: '3.8'
2

3
services:
4
  pubsub-worker:
5
    build:
6
      context: .
7
      dockerfile: Dockerfile
8

9
    volumes:
10
      # Mount your local ADC
11
      - ~/.config/gcloud:/home/app/.config/gcloud:ro
12

13
    environment:
14
      # Critical
15
      HOME: /home/app
16

17
      # Your config
18
      GCP_PROJECT_ID: my-gcp-project
19
      PUBSUB_TOPIC_NAME: user-events
20
      PUBSUB_SUBSCRIPTION_NAME: user-events-worker
21

22
    # Optional: ensure container stops gracefully
23
    stop_signal: SIGTERM
24
    stop_grace_period: 10s

Complete Dockerfile (Correct)

1
FROM oven/bun:1-alpine
2

3
WORKDIR /app
4

5
# Copy code
6
COPY . .
7

8
# Install dependencies
9
RUN bun install --frozen-lockfile
10

11
# Create non-root user
12
RUN addgroup -S app && adduser -S app -G app
13
USER app
14

15
# Run
16
CMD ["bun", "run", "src/worker.ts"]

Now when you run:

docker compose up

Your container will:

1. Mount your local ADC to /home/app/.config/gcloud
2. Set HOME=/home/app so the client finds it
3. Run as user app (non-root)
4. Access Pub/Sub with your credentials

Part 9: The Most Common Mistake

This pattern is everywhere, and it’s wrong:

Don’t do this:

1
// Auto-creating topics at runtime
2
const topic = await pubsub.topic('logs').get({
3
  autoCreate: true
4
});
5

6
await topic.publishMessage({ json: { message: 'hello' } });

Why it’s wrong:

1. Requires pubsub.topics.create permission (too much)
2. Hides infrastructure problems until production
3. Creates unpredictable topics in other environments
4. Your app shouldn’t know how to create topics

Do this instead:

1
const topic = pubsub.topic('logs');
2

3
// Just publish. If topic doesn't exist, publishing fails clearly.
4
await topic.publishMessage({ json: { message: 'hello' } });

If the topic doesn’t exist:

• Publishing fails with NOT_FOUND
• Your infra team gets alerted
• You fix the infrastructure
• Deploy again

This is the correct pattern.

Part 10: Docker Debugging Checklist

When Pub/Sub fails inside Docker:

1. Does bun run test-pubsub.ts (make a small script just pushing to the topic) work on your host?

   • If no, your local setup is wrong. Fix it before Docker.

2. Is GCP_PROJECT_ID actually defined inside the container?

   docker compose exec pubsub-worker env | grep GCP_PROJECT_ID

3. Is the topic name exactly correct?

   # Check if topic exists in GCP
   gcloud pubsub topics list

4. Are you calling exists(), get(), or autoCreate?

   • Don’t do this. Just use the topic object directly.

5. Does the runtime identity (service account) have the right IAM role?

   gcloud projects get-iam-policy YOUR_PROJECT \
     --flatten="bindings[].members" \
     --filter="bindings.members:serviceAccount:*"

6. Is ADC mounted to the correct HOME path?

   docker compose exec pubsub-worker ls -la ~/.config/gcloud/

If #1 works locally and #4 is false, that’s usually the bug.

Part 11: Production (Cloud Run / GKE)

In managed GCP environments (Cloud Run, GKE, Compute Engine), everything simplifies.

Cloud Run

1
FROM oven/bun:1-alpine
2
WORKDIR /app
3
COPY . .
4
RUN bun install --frozen-lockfile
5
CMD ["bun", "run", "src/worker.ts"]

Deploy:

gcloud run deploy my-worker \
  --source . \
  --runtime nodejs18

Assign IAM role:

gcloud run services add-iam-policy-binding my-worker \
  --member=serviceAccount:my-service-account@my-project.iam.gserviceaccount.com \
  --role=roles/pubsub.publisher

Your Bun code doesn’t change:

1
const pubsub = new PubSub({
2
  projectId: process.env.GCP_PROJECT_ID,
3
  // ADC is automatic in Cloud Run
4
});

Why it works:

• Cloud Run provides a service account automatically
• ADC works with that service account
• No secrets, no mounting, no complexity

GKE

Create a Kubernetes service account with Workload Identity:

gcloud iam service-accounts create my-bun-app

gcloud iam service-accounts add-iam-policy-binding \
  my-bun-app@my-project.iam.gserviceaccount.com \
  --role roles/pubsub.publisher

Link to your Kubernetes service account:

gcloud iam service-accounts add-iam-policy-binding \
  my-bun-app@my-project.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:my-project.svc.id.goog[default/my-bun-app]"

Deploy:

1
apiVersion: v1
2
kind: ServiceAccount
3
metadata:
4
  name: my-bun-app
5
  annotations:
6
    iam.gke.io/gcp-service-account: my-bun-app@my-project.iam.gserviceaccount.com
7
---
8
apiVersion: apps/v1
9
kind: Deployment
10
metadata:
11
  name: my-bun-app
12
spec:
13
  replicas: 3
14
  template:
15
    spec:
16
      serviceAccountName: my-bun-app
17
      containers:
18
      - name: worker
19
        image: my-app:latest
20
        env:
21
        - name: GCP_PROJECT_ID
22
          value: my-project
23
        - name: PUBSUB_TOPIC_NAME
24
          value: user-events

Again, your Bun code doesn’t change. ADC handles it.

Part 12: A Complete Example (End-to-End)

Publisher Service

1
import { PubSub } from '@google-cloud/pubsub';
2

3
const pubsub = new PubSub({
4
  projectId: process.env.GCP_PROJECT_ID,
5
});
6

7
const topic = pubsub.topic(process.env.PUBSUB_TOPIC_NAME!);
8

9
// Simulate events
10
setInterval(async () => {
11
  const event = {
12
    userId: `user_${Math.floor(Math.random() * 1000)}`,
13
    action: ['login', 'logout', 'purchase'][Math.floor(Math.random() * 3)],
14
    timestamp: Date.now(),
15
  };
16

17
  try {
18
    await topic.publishMessage({
19
      json: event,
20
      attributes: {
21
        source: 'user-service',
22
        version: '1.0',
23
      },
24
    });
25
    console.log(`Published: ${event.action}`);
26
  } catch (error) {
27
    console.error('Failed to publish:', error.message);
28
  }
29
}, 5000);

Subscriber Service

1
import { PubSub } from '@google-cloud/pubsub';
2

3
const pubsub = new PubSub({
4
  projectId: process.env.GCP_PROJECT_ID,
5
});
6

7
const subscription = pubsub.subscription(
8
  process.env.PUBSUB_SUBSCRIPTION_NAME!
9
);
10

11
subscription.on('message', (message) => {
12
  try {
13
    const event = JSON.parse(message.data.toString());
14

15
    console.log(`Received: ${event.action} from ${event.userId}`);
16

17
    // Process the event (e.g., update database)
18
    // ...
19

20
    message.ack();
21
  } catch (error) {
22
    console.error('Failed to process message:', error.message);
23
    message.nack();
24
  }
25
});
26

27
subscription.on('error', (error) => {
28
  console.error('Subscription error:', error);
29
});
30

31
process.on('SIGTERM', async () => {
32
  console.log('Shutting down...');
33
  subscription.close();
34
  await pubsub.close();
35
});

Docker Compose

1
version: '3.8'
2

3
services:
4
  publisher:
5
    build: .
6
    volumes:
7
      - ~/.config/gcloud:/home/app/.config/gcloud:ro
8
    environment:
9
      HOME: /home/app
10
      GCP_PROJECT_ID: my-project
11
      PUBSUB_TOPIC_NAME: user-events
12
    command: bun run src/publisher.ts
13

14
  subscriber:
15
    build: .
16
    volumes:
17
      - ~/.config/gcloud:/home/app/.config/gcloud:ro
18
    environment:
19
      HOME: /home/app
20
      GCP_PROJECT_ID: my-project
21
      PUBSUB_SUBSCRIPTION_NAME: user-events-worker
22
    command: bun run src/subscriber.ts

Run locally:

docker compose up

Part 13: Troubleshooting Guide

Conclusion: Keep It Simple

Pub/Sub itself is solid. Most pain comes from:

1. Mixing responsibilities — Apps shouldn’t create infrastructure
2. Over-permissioning — Give only what’s needed
3. Misunderstanding ADC — Especially in Docker
4. Calling exists() or get() at runtime — Just use the topic/subscription object

Once you embrace these patterns, Pub/Sub becomes boring—in the best way.

Your checklist:

• Only publish and consume at runtime
• Provision topics/subscriptions upfront
• Use ADC locally
• Mount ADC in Docker
• ADC is automatic in Cloud Run/GKE
• Assign minimal IAM roles
• Log environment variables when debugging

If your Pub/Sub setup feels fragile, it’s usually a design issue, not a tooling issue.

Happy shipping 🚀

Further Reading

• Google Cloud Pub/Sub Documentation
• Application Default Credentials
• Pub/Sub IAM Roles
• @google-cloud/pubsub npm