Add optional onError callback for non-fatal transport issues

Co-authored-by: Eric Allam <eric@trigger.dev>

Author: cursoragent

docs/tasks/streams.mdx

@@ -614,6 +614,7 @@ The default payload sent to your task is a rich, typed object that includes:
 - `triggerOptions` as an object or resolver function (sync or async)
 - `runStore` for custom reconnect-state persistence (including async stores)
 - `onTriggeredRun` callback (sync or async) to persist or observe run IDs
+- `onError` callback to observe non-fatal transport issues
 - headers passed through transport can be object, `Headers`, or tuple arrays
 
 ```ts

packages/ai/README.md

@@ -60,6 +60,7 @@ Typed request option helper aliases are exported:
 - `TriggerChatSendMessagesOptions`
 - `TriggerChatReconnectOptions`
 - `TriggerChatHeadersInput`
+- `TriggerChatTransportError` / `TriggerChatOnError`
 
 ```ts
 import type { TriggerChatTransportPayload } from "@trigger.dev/ai";
@@ -128,6 +129,9 @@ class MemoryStore implements TriggerChatRunStore {
 `onTriggeredRun` can also be async, which is useful for persisting run IDs before
 the chat stream is consumed. Callback failures are ignored so chat streaming can continue.
 
+You can optionally provide `onError` to observe non-fatal transport errors
+(for example callback failures or reconnect setup issues).
+
 ## Reconnect semantics
 
 - `reconnectToStream({ chatId })` resumes only while a stream is still active.

packages/ai/src/chatTransport.test.ts

@@ -9,6 +9,7 @@ import {
 import type { TriggerChatStream } from "./types.js";
 import type { UIMessage, UIMessageChunk } from "ai";
 import type {
+  TriggerChatTransportError,
   TriggerChatRunState,
   TriggerChatRunStore,
 } from "./types.js";
@@ -864,6 +865,7 @@ describe("TriggerChatTransport", function () {
 
   it("continues streaming when onTriggeredRun callback throws", async function () {
     let callbackCalled = false;
+    const errors: TriggerChatTransportError[] = [];
 
     const server = await startServer(function (req, res) {
       if (req.method === "POST" && req.url === "/api/v1/tasks/chat-task/trigger") {
@@ -909,6 +911,9 @@ describe("TriggerChatTransport", function () {
         callbackCalled = true;
         throw new Error("callback failed");
       },
+      onError: function onError(error) {
+        errors.push(error);
+      },
     });
 
     const stream = await transport.sendMessages({
@@ -922,6 +927,71 @@ describe("TriggerChatTransport", function () {
     const chunks = await readChunks(stream);
     expect(callbackCalled).toBe(true);
     expect(chunks).toHaveLength(2);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({
+      phase: "onTriggeredRun",
+      chatId: "chat-callback-error",
+      runId: "run_callback_error",
+    });
+    expect(errors[0]?.error.message).toBe("callback failed");
+  });
+
+  it("ignores failures from onError callback", async function () {
+    const server = await startServer(function (req, res) {
+      if (req.method === "POST" && req.url === "/api/v1/tasks/chat-task/trigger") {
+        res.writeHead(200, {
+          "content-type": "application/json",
+          "x-trigger-jwt": "pk_run_onerror_fail",
+        });
+        res.end(JSON.stringify({ id: "run_onerror_fail" }));
+        return;
+      }
+
+      if (req.method === "GET" && req.url === "/realtime/v1/streams/run_onerror_fail/chat-stream") {
+        res.writeHead(200, {
+          "content-type": "text/event-stream",
+        });
+        writeSSE(
+          res,
+          "1-0",
+          JSON.stringify({ type: "text-start", id: "onerror_fail_1" })
+        );
+        writeSSE(
+          res,
+          "2-0",
+          JSON.stringify({ type: "text-end", id: "onerror_fail_1" })
+        );
+        res.end();
+        return;
+      }
+
+      res.writeHead(404);
+      res.end();
+    });
+
+    const transport = new TriggerChatTransport({
+      task: "chat-task",
+      stream: "chat-stream",
+      accessToken: "pk_trigger",
+      baseURL: server.url,
+      onTriggeredRun: async function onTriggeredRun() {
+        throw new Error("callback failed");
+      },
+      onError: async function onError() {
+        throw new Error("onError failed");
+      },
+    });
+
+    const stream = await transport.sendMessages({
+      trigger: "submit-message",
+      chatId: "chat-onerror-fail",
+      messageId: undefined,
+      messages: [],
+      abortSignal: undefined,
+    });
+
+    const chunks = await readChunks(stream);
+    expect(chunks).toHaveLength(2);
   });
 
   it("cleans run store state when stream completes", async function () {

packages/ai/src/chatTransport.ts

@@ -15,6 +15,7 @@ import type {
 } from "ai";
 import type {
   TriggerChatHeadersInput,
+  TriggerChatOnError,
   TriggerChatReconnectOptions,
   TriggerChatSendMessagesOptions,
   TriggerChatOnTriggeredRun,
@@ -79,6 +80,7 @@ type TriggerChatTransportCommonOptions<
     | TriggerChatTriggerOptionsResolver<UI_MESSAGE>;
   runStore?: TriggerChatRunStore;
   onTriggeredRun?: TriggerChatOnTriggeredRun;
+  onError?: TriggerChatOnError;
 };
 
 type TriggerChatTransportMapperRequirement<
@@ -133,6 +135,7 @@ export class TriggerChatTransport<
   private readonly previewBranch: string | undefined;
   private readonly requestOptions: ApiRequestOptions | undefined;
   private readonly onTriggeredRun: TriggerChatOnTriggeredRun | undefined;
+  private readonly onError: TriggerChatOnError | undefined;
 
   constructor(options: TriggerChatTransportOptions<UI_MESSAGE, PAYLOAD>) {
     this.task = options.task;
@@ -151,6 +154,7 @@ export class TriggerChatTransport<
       this.requestOptions
     );
     this.onTriggeredRun = options.onTriggeredRun;
+    this.onError = options.onError;
   }
 
   public async sendMessages(
@@ -180,7 +184,13 @@ export class TriggerChatTransport<
         await this.onTriggeredRun({
           ...runState,
         });
-      } catch {
+      } catch (error) {
+        await this.reportError({
+          phase: "onTriggeredRun",
+          chatId: runState.chatId,
+          runId: runState.runId,
+          error: normalizeError(error),
+        });
         // Ignore callback errors so chat streaming can continue.
       }
     }
@@ -207,10 +217,16 @@ export class TriggerChatTransport<
     let stream: ReadableStream<SSEStreamPart<InferUIMessageChunk<UI_MESSAGE>>>;
     try {
       stream = await this.fetchRunStream(runState, undefined, runState.lastEventId);
-    } catch {
+    } catch (error) {
       runState.isActive = false;
       await this.runStore.set(runState);
       await this.runStore.delete(options.chatId);
+      await this.reportError({
+        phase: "reconnect",
+        chatId: runState.chatId,
+        runId: runState.runId,
+        error: normalizeError(error),
+      });
       return null;
     }
 
@@ -291,6 +307,12 @@ export class TriggerChatTransport<
         runState.isActive = false;
         await this.runStore.set(runState);
         await this.runStore.delete(chatId);
+        await this.reportError({
+          phase: "consumeTrackingStream",
+          chatId: runState.chatId,
+          runId: runState.runId,
+          error: new Error("Stream tracking failed"),
+        });
       }
     }
   }
@@ -314,6 +336,25 @@ export class TriggerChatTransport<
 
     return `${normalizedBaseUrl}/realtime/v1/streams/${encodedRunId}/${encodedStreamKey}`;
   }
+
+  private async reportError(
+    event: {
+      phase: "onTriggeredRun" | "consumeTrackingStream" | "reconnect";
+      chatId: string;
+      runId: string;
+      error: Error;
+    }
+  ) {
+    if (!this.onError) {
+      return;
+    }
+
+    try {
+      await this.onError(event);
+    } catch {
+      // Never let error callbacks interfere with transport behavior.
+    }
+  }
 }
 
 export function createTriggerChatTransport<
@@ -469,3 +510,11 @@ async function createTriggerTaskOptions(
 }
 
 export type { TriggerChatTaskContext };
+
+function normalizeError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  return new Error(String(error));
+}

packages/ai/src/chatTransport.types.test.ts

@@ -4,6 +4,7 @@ import {
   createTriggerChatTransport,
   TriggerChatTransport,
   TriggerChatTransportOptions,
+  type TriggerChatTransportError,
   type TriggerChatHeadersInput,
   type TriggerChatReconnectOptions,
   type TriggerChatSendMessagesOptions,
@@ -88,6 +89,9 @@ it("accepts async payload mappers and trigger option resolvers", function () {
     onTriggeredRun: async function onTriggeredRun(_state) {
       return;
     },
+    onError: async function onError(_error: TriggerChatTransportError) {
+      return;
+    },
   };
 
   expectTypeOf(options).toBeObject();

packages/ai/src/index.ts

@@ -7,6 +7,7 @@ export {
 } from "./chatTransport.js";
 export type {
   TriggerChatHeadersInput,
+  TriggerChatOnError,
   TriggerChatPayloadMapper,
   TriggerChatOnTriggeredRun,
   TriggerChatReconnectOptions,
@@ -15,6 +16,8 @@ export type {
   TriggerChatSendMessagesOptions,
   TriggerChatStream,
   TriggerChatTaskContext,
+  TriggerChatTransportError,
+  TriggerChatTransportErrorPhase,
   TriggerChatTransportPayload,
   TriggerChatTransportRequest,
   TriggerChatTransportTrigger,

packages/ai/src/types.ts

@@ -70,6 +70,22 @@ export type TriggerChatOnTriggeredRun = (
   state: TriggerChatRunState
 ) => MaybePromise<void>;
 
+export type TriggerChatTransportErrorPhase =
+  | "onTriggeredRun"
+  | "consumeTrackingStream"
+  | "reconnect";
+
+export type TriggerChatTransportError = {
+  phase: TriggerChatTransportErrorPhase;
+  chatId: string;
+  runId: string;
+  error: Error;
+};
+
+export type TriggerChatOnError = (
+  error: TriggerChatTransportError
+) => MaybePromise<void>;
+
 export type TriggerChatStream<
   UI_MESSAGE extends UIMessage = UIMessage,
 > =