Report send-phase errors through onError callback

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

Author: cursoragent

docs/tasks/streams.mdx

@@ -617,6 +617,10 @@ The default payload sent to your task is a rich, typed object that includes:
 - `onError` callback to observe non-fatal transport issues
 - headers passed through transport can be object, `Headers`, or tuple arrays
 
+`onError` receives phase-aware details (`payloadMapper`, `triggerOptions`, `triggerTask`,
+`onTriggeredRun`, `consumeTrackingStream`, `reconnect`) plus `chatId`, optional `runId`,
+and the underlying `error`.
+
 ```ts
 import type { TriggerChatRunState, TriggerChatRunStore } from "@trigger.dev/ai";
 

packages/ai/README.md

@@ -135,9 +135,9 @@ You can optionally provide `onError` to observe non-fatal transport errors
 
 The callback receives:
 
-- `phase`: `"onTriggeredRun" | "consumeTrackingStream" | "reconnect"`
+- `phase`: `"payloadMapper" | "triggerOptions" | "triggerTask" | "onTriggeredRun" | "consumeTrackingStream" | "reconnect"`
 - `chatId`
-- `runId`
+- `runId` (may be `undefined` before a run is created)
 - `error`
 
 ## Reconnect semantics

packages/ai/src/chatTransport.test.ts

@@ -732,6 +732,7 @@ describe("TriggerChatTransport", function () {
 
   it("surfaces payload mapper errors and does not trigger runs", async function () {
     let triggerCalls = 0;
+    const errors: TriggerChatTransportError[] = [];
 
     const server = await startServer(function (req, res) {
       if (req.method === "POST" && req.url === "/api/v1/tasks/chat-task/trigger") {
@@ -755,6 +756,9 @@ describe("TriggerChatTransport", function () {
       payloadMapper: async function payloadMapper() {
         throw new Error("mapper failed");
       },
+      onError: function onError(error) {
+        errors.push(error);
+      },
     });
 
     await expect(
@@ -768,10 +772,18 @@ describe("TriggerChatTransport", function () {
     ).rejects.toThrowError("mapper failed");
 
     expect(triggerCalls).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({
+      phase: "payloadMapper",
+      chatId: "chat-mapper-failure",
+      runId: undefined,
+    });
+    expect(errors[0]?.error.message).toBe("mapper failed");
   });
 
   it("surfaces trigger options resolver errors and does not trigger runs", async function () {
     let triggerCalls = 0;
+    const errors: TriggerChatTransportError[] = [];
 
     const server = await startServer(function (req, res) {
       if (req.method === "POST" && req.url === "/api/v1/tasks/chat-task/trigger") {
@@ -792,6 +804,9 @@ describe("TriggerChatTransport", function () {
       triggerOptions: async function triggerOptions() {
         throw new Error("trigger options failed");
       },
+      onError: function onError(error) {
+        errors.push(error);
+      },
     });
 
     await expect(
@@ -805,6 +820,59 @@ describe("TriggerChatTransport", function () {
     ).rejects.toThrowError("trigger options failed");
 
     expect(triggerCalls).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({
+      phase: "triggerOptions",
+      chatId: "chat-trigger-failure",
+      runId: undefined,
+    });
+    expect(errors[0]?.error.message).toBe("trigger options failed");
+  });
+
+  it("reports trigger task request failures through onError", async function () {
+    const errors: TriggerChatTransportError[] = [];
+    const server = await startServer(function (_req, res) {
+      res.writeHead(500, {
+        "content-type": "application/json",
+      });
+      res.end(JSON.stringify({ error: "task trigger failed" }));
+    });
+
+    const transport = new TriggerChatTransport({
+      task: "chat-task",
+      stream: "chat-stream",
+      accessToken: "pk_trigger",
+      baseURL: server.url,
+      requestOptions: {
+        retry: {
+          maxAttempts: 1,
+          minTimeoutInMs: 1,
+          maxTimeoutInMs: 1,
+          factor: 1,
+          randomize: false,
+        },
+      },
+      onError: function onError(error) {
+        errors.push(error);
+      },
+    });
+
+    await expect(
+      transport.sendMessages({
+        trigger: "submit-message",
+        chatId: "chat-trigger-request-failure",
+        messageId: undefined,
+        messages: [],
+        abortSignal: undefined,
+      })
+    ).rejects.toThrowError("task trigger failed");
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatchObject({
+      phase: "triggerTask",
+      chatId: "chat-trigger-request-failure",
+      runId: undefined,
+    });
   });
 
   it("supports creating transport with factory function", async function () {

packages/ai/src/chatTransport.ts

@@ -161,12 +161,47 @@ export class TriggerChatTransport<
     options: TriggerChatSendMessagesOptions<UI_MESSAGE>
   ): Promise<ReadableStream<UIMessageChunk>> {
     const transportRequest = createTransportRequest<UI_MESSAGE>(options);
-    const payload = await this.payloadMapper(transportRequest);
-    const triggerOptions = await resolveTriggerOptions<UI_MESSAGE>(
-      this.triggerOptions,
-      transportRequest
-    );
-    const run = await this.triggerTask(payload, triggerOptions);
+    let payload: PAYLOAD;
+    try {
+      payload = await this.payloadMapper(transportRequest);
+    } catch (error) {
+      await this.reportError({
+        phase: "payloadMapper",
+        chatId: options.chatId,
+        runId: undefined,
+        error: normalizeError(error),
+      });
+      throw error;
+    }
+
+    let triggerOptions: TriggerOptions | undefined;
+    try {
+      triggerOptions = await resolveTriggerOptions<UI_MESSAGE>(
+        this.triggerOptions,
+        transportRequest
+      );
+    } catch (error) {
+      await this.reportError({
+        phase: "triggerOptions",
+        chatId: options.chatId,
+        runId: undefined,
+        error: normalizeError(error),
+      });
+      throw error;
+    }
+
+    let run: TriggerTaskResponse;
+    try {
+      run = await this.triggerTask(payload, triggerOptions);
+    } catch (error) {
+      await this.reportError({
+        phase: "triggerTask",
+        chatId: options.chatId,
+        runId: undefined,
+        error: normalizeError(error),
+      });
+      throw error;
+    }
 
     const runState: TriggerChatRunState = {
       chatId: options.chatId,
@@ -339,9 +374,15 @@ export class TriggerChatTransport<
 
   private async reportError(
     event: {
-      phase: "onTriggeredRun" | "consumeTrackingStream" | "reconnect";
+      phase:
+        | "payloadMapper"
+        | "triggerOptions"
+        | "triggerTask"
+        | "onTriggeredRun"
+        | "consumeTrackingStream"
+        | "reconnect";
       chatId: string;
-      runId: string;
+      runId: string | undefined;
       error: Error;
     }
   ) {

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

@@ -108,9 +108,16 @@ it("exposes strongly typed onError callback payloads", function () {
 
 function createTypedOnErrorCallback(): TriggerChatOnError {
   async function onError(error: TriggerChatTransportError) {
-    expectTypeOf(error.phase).toEqualTypeOf<"onTriggeredRun" | "consumeTrackingStream" | "reconnect">();
+    expectTypeOf(error.phase).toEqualTypeOf<
+      | "payloadMapper"
+      | "triggerOptions"
+      | "triggerTask"
+      | "onTriggeredRun"
+      | "consumeTrackingStream"
+      | "reconnect"
+    >();
     expectTypeOf(error.chatId).toEqualTypeOf<string>();
-    expectTypeOf(error.runId).toEqualTypeOf<string>();
+    expectTypeOf(error.runId).toEqualTypeOf<string | undefined>();
     expectTypeOf(error.error).toEqualTypeOf<Error>();
   }
 
@@ -196,7 +203,7 @@ it("accepts custom onError callbacks via options typing", function () {
     accessToken: "pk_test",
     onError: function onError(error) {
       expectTypeOf(error.chatId).toEqualTypeOf<string>();
-      expectTypeOf(error.runId).toEqualTypeOf<string>();
+      expectTypeOf(error.runId).toEqualTypeOf<string | undefined>();
     },
   });
 

packages/ai/src/types.ts

@@ -71,14 +71,17 @@ export type TriggerChatOnTriggeredRun = (
 ) => MaybePromise<void>;
 
 export type TriggerChatTransportErrorPhase =
+  | "payloadMapper"
+  | "triggerOptions"
+  | "triggerTask"
   | "onTriggeredRun"
   | "consumeTrackingStream"
   | "reconnect";
 
 export type TriggerChatTransportError = {
   phase: TriggerChatTransportErrorPhase;
   chatId: string;
-  runId: string;
+  runId: string | undefined;
   error: Error;
 };