From 5d6085dcffb037edd231bb6ae21bb737c30f731b Mon Sep 17 00:00:00 2001
From: Iss <74388823+isshaddad@users.noreply.github.com>
Date: Sat, 14 Feb 2026 14:02:00 -0500
Subject: [PATCH] docs: Realtime skipColumns and Bun indexing troubleshooting
 (#3054)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the skipColumns option on useRealtimeRun and
useRealtimeRunsWithTag for status-only subscriptions (smaller payloads,
e.g. for progress/completion UI). Adds a troubleshooting section for the
“Failed to index deployment” source-map error when using the Bun
runtime, with a pnpm patch workaround and link to the GitHub issue
---
 docs/realtime/react-hooks/subscribe.mdx | 26 +++++++++++++++++++++++++
 docs/troubleshooting.mdx                |  4 ++++
 2 files changed, 30 insertions(+)

diff --git a/docs/realtime/react-hooks/subscribe.mdx b/docs/realtime/react-hooks/subscribe.mdx
index 4cf0a79da..41ef2b61f 100644
--- a/docs/realtime/react-hooks/subscribe.mdx
+++ b/docs/realtime/react-hooks/subscribe.mdx
@@ -93,6 +93,32 @@ export function MyComponent({
 }
 ```
 
+When you only need run status (for example, a progress bar or completion badge), you can omit large fields like `payload` and `output` by passing `skipColumns`. This reduces the data sent over the wire and avoids issues such as "Large HTTP Payload" warnings in tools like Sentry.
+
+```tsx
+import { useRealtimeRun } from "@trigger.dev/react-hooks";
+
+export function RunStatusBadge({
+  runId,
+  publicAccessToken,
+}: {
+  runId: string;
+  publicAccessToken: string;
+}) {
+  const { run, error } = useRealtimeRun(runId, {
+    accessToken: publicAccessToken,
+    skipColumns: ["payload", "output"],
+  });
+
+  if (error) return <span>Error</span>;
+  if (!run) return <span>Loading…</span>;
+
+  return <span>Status: {run.status}</span>;
+}
+```
+
+You can skip any of: `payload`, `output`, `metadata`, `startedAt`, `delayUntil`, `queuedAt`, `expiredAt`, `completedAt`, `number`, `isTest`, `usageDurationMs`, `costInCents`, `baseCostInCents`, `ttl`, `payloadType`, `outputType`, `runTags`, `error`. The `useRealtimeRunsWithTag` hook also accepts a `skipColumns` option in the same way.
+
 See our [run object reference](/realtime/run-object) for the complete schema and [How it Works documentation](/realtime/how-it-works) for more technical details.
 
 ### useRealtimeRunsWithTag
diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx
index 13d9216f8..bd612110e 100644
--- a/docs/troubleshooting.mdx
+++ b/docs/troubleshooting.mdx
@@ -97,6 +97,10 @@ export default defineConfig({
 
 If you see this error, add pino (and any other associated packages) to your `external` build settings in your `trigger.config.ts` file. Learn more about the `external` setting in the [config docs](/config/config-file#external).
 
+### `Failed to index deployment` with `Column must be greater than or equal to 0, got -1`
+
+This can occur when using `runtime: "bun"` during the indexing phase (we load and execute your task files to discover exports). A short-term workaround is to [pnpm patch](https://pnpm.io/cli/patch) the `source-map` package. See [this GitHub issue](https://github.com/triggerdotdev/trigger.dev/issues/3045) for the patch details.
+
 ### `reactDOMServer.renderToPipeableStream is not a function` when using react-email
 
 If you see this error when using `@react-email/render`: