Error handling

chat.agent errors fall into four layers, each with different recovery semantics. The default behavior is conversation-preserving: a thrown error in a hook or run() does not kill the chat. The current turn ends with an error chunk, and the agent waits for the user’s next message.

Error layers at a glance

Layer	Source	Default behavior	Recovery
Stream	`streamText` errors mid-response (rate limits, model API failures)	`onError` callback converts to error chunk	Sanitize message via `uiMessageStreamOptions.onError`
Hook / turn	Throws in `onValidateMessages`, `onTurnStart`, `run`, etc.	Error chunk + turn-complete written to stream; conversation continues	Catch in your hook, or rely on default
Run	Unhandled exception escapes the run	Run fails. No retry by default. Standard task `onFailure` fires.	`onFailure` task hook
Frontend	Stream delivers `{ type: "error", errorText }`	`useChat` exposes via `error` field and `onError` callback	Show toast, retry button, etc.

Stream errors mid-turn

When the model API errors mid-response (rate limits, network failures, malformed output), the AI SDK’s streamText calls the onError callback. Use uiMessageStreamOptions.onError to convert the error to a user-friendly string. The string is sent to the frontend as an error chunk.

import { chat } from "@trigger.dev/sdk/ai";
import { anthropic } from "@ai-sdk/anthropic";

export const myChat = chat.agent({
  id: "my-chat",
  uiMessageStreamOptions: {
    onError: (error) => {
      console.error("Stream error:", error);
      if (error instanceof Error && error.message.includes("rate limit")) {
        return "Rate limited. Please wait a moment and try again.";
      }
      if (error instanceof Error && error.message.includes("context_length")) {
        return "This conversation is too long. Please start a new chat.";
      }
      return "Something went wrong while generating a response. Please try again.";
    },
  },
  run: async ({ messages, signal, streamText }) => {
    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
  },
});

Returning a string from onError is what gets shown to the user. Do not return raw error messages — they may leak internal details (API keys, stack traces, etc.).

The frontend receives this as an error chunk that useChat exposes via its error field:

const { messages, error } = useChat({ transport });

{error && <div className="text-red-600">{error.message}</div>}

Hook and turn errors

If any lifecycle hook (onValidateMessages, onChatStart, onTurnStart, hydrateMessages, onAction, prepareMessages, onBeforeTurnComplete, onTurnComplete) or run() throws an unhandled exception, the turn loop catches it:

Writes { type: "error", errorText: error.message } to the stream
Writes a turn-complete chunk to close the turn
Waits for the next user message

The conversation stays alive. The user can send another message and continue.

export const myChat = chat.agent({
  id: "my-chat",
  onTurnStart: async ({ chatId, uiMessages }) => {
    // If this throws, the turn ends with an error chunk
    // and the agent waits for the next message
    await db.chat.update({ where: { id: chatId }, data: { messages: uiMessages } });
  },
  run: async ({ messages, signal, streamText }) => {
    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
  },
});

Catching errors in your own hooks

For granular control, wrap your hook code in try/catch and decide what to do. Common patterns:

onValidateMessages: async ({ messages }) => {
  try {
    return await validateUIMessages({ messages, tools: chatTools });
  } catch (err) {
    // Log to your error tracking service
    Sentry.captureException(err);
    // Throw a user-facing error message — this becomes the error chunk
    throw new Error("Your message contains invalid data and could not be sent.");
  }
},

The Error.message you throw is sent verbatim to the frontend as the error chunk’s errorText. Use messages safe for end users.

Catching errors inside `run()`

Catch errors from work you await inside run(), such as loading application data. Errors emitted after streamText() returns reach the response stream instead. Record those in onTurnComplete, which receives the partial response and the error.

Saving error state to your DB

To persist errors for debugging or undo, use onTurnComplete (which fires even after errors) or the standard task onComplete hook.

Using `onTurnComplete`

onTurnComplete fires after every turn — successful or errored. On an errored turn responseMessage is undefined or partial and error carries the thrown value (with finishReason set to "error"). Use this to mark the turn as failed:

onTurnComplete: async ({ chatId, uiMessages, responseMessage, stopped, error }) => {
  // Persist the messages regardless of error state
  await db.chat.update({
    where: { id: chatId },
    data: {
      messages: uiMessages,
      // `error` is set when the turn threw
      lastTurnStatus: error ? "errored" : stopped ? "stopped" : "ok",
    },
  });
},

Using the standard `onFailure` task hook

For run-level failures (the entire run dies), use the standard task onFailure hook. This fires when the run terminates with an unhandled exception:

chat.agent({
  id: "my-chat",
  onFailure: async ({ error, ctx }) => {
    // Log run-level failure to your monitoring service
    await monitoring.recordRunFailure({
      runId: ctx.run.id,
      chatId: ctx.run.tags.find(t => t.startsWith("chat:"))?.slice(5),
      error: error.message,
    });
  },
  run: async ({ messages, signal, streamText }) => {
    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
  },
});

chat.agent defaults to one run attempt. Setting oomMachine enables one additional attempt on the larger machine after an out-of-memory failure. Recover from a failed turn by sending another message or calling regenerate().

Recovery patterns

Pattern 1: Undo to last successful response

A common pattern is to let the user “undo” the failed turn and try again. Combine chat.history.rollbackTo with a custom action:

chat.agent({
  id: "my-chat",
  actionSchema: z.discriminatedUnion("type", [
    z.object({ type: z.literal("undo") }),
  ]),
  onAction: async ({ action, uiMessages }) => {
    if (action.type === "undo") {
      // Find the last user message and roll back to it
      const lastUserIdx = [...uiMessages].reverse().findIndex(m => m.role === "user");
      if (lastUserIdx !== -1) {
        const targetIdx = uiMessages.length - 1 - lastUserIdx - 1;
        chat.history.slice(0, targetIdx + 1);
      }
    }
  },
  run: async ({ messages, signal, streamText }) => {
    return streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal });
  },
});

On the frontend, show an “Undo” button when an error occurs:

app/chat/UndoButton.tsx

import { useChatActions } from "@trigger.dev/sdk/chat/react";

const { sendAction } = useChatActions({ sendMessage });

{error && (
  <button onClick={() => sendAction({ type: "undo" })}>
    Undo and try again
  </button>
)}

Pattern 2: Retry the last message

For transient errors (network blips, rate limits), the simplest recovery is to re-send the last user message. The AI SDK’s useChat provides regenerate():

const { messages, error, regenerate } = useChat({ transport });

{error && (
  <button onClick={() => regenerate()}>Retry</button>
)}

regenerate() removes the last assistant response and re-sends. If your storage implements loadContext, handle trigger === "regenerate-message" there: remove trailing assistant messages from the active branch so the model receives the last user message as its prompt.

Pattern 3: Save partial responses

When a stream fails or you stop a response, transcript storage preserves the partial assistant message with final: false. Keep that flag in your storage adapter so a reload doesn’t present an incomplete answer as finished. Use onTurnComplete to record the outcome. Check error or stopped before classifying a response as partial:

trigger/chat.ts

onTurnComplete: async ({ chatId, responseMessage, error, stopped }) => {
  if (!responseMessage || (!error && !stopped)) return;

  await db.partialResponse.upsert({
    where: { id: responseMessage.id },
    create: {
      id: responseMessage.id,
      chatId,
      message: responseMessage,
      reason: stopped ? "stopped" : "errored",
    },
    update: {
      message: responseMessage,
      reason: stopped ? "stopped" : "errored",
    },
  });
},

Pattern 4: Retry with another model

streamText() returns before the provider finishes streaming. A try/catch around that call only catches setup failures; it doesn’t catch errors that arrive later in the stream. For a streamed provider failure, let the failed turn finish, choose a fallback model on your server, then regenerate the response. The partial response remains available until you replace it. Check whether tools already performed side effects before retrying, and make those operations idempotent.

What gets written to the stream on error

When an error occurs at any layer, the frontend’s UIMessageChunk stream surfaces an error chunk:

{ "type": "error", "errorText": "Rate limited. Please wait a moment and try again." }

A turn-complete control record follows on session.out (header-form, not a data chunk — see turn-complete control record for the wire format) to mark the turn as done. The AI SDK’s useChat processes this and:

Sets useChat’s error field to an Error with message = errorText
Calls the user’s onError callback (if set)
Sets status to "error". Sending another message or regenerating starts a new request.

const { messages, error, status } = useChat({
  transport,
  onError: (err) => {
    toast.error(err.message);
  },
});

Frontend error handling

Showing the error to the user

function Chat() {
  const transport = useTriggerChatTransport({
    task: "my-chat",
    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
    startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
  });
  const { messages, error, sendMessage } = useChat({ transport });

  return (
    <div>
      {messages.map(m => /* ... */)}
      {error && (
        <div className="rounded border border-red-300 bg-red-50 p-3">
          <p className="text-red-700">{error.message}</p>
        </div>
      )}
      <form onSubmit={(e) => { e.preventDefault(); sendMessage(/* ... */); }}>
        {/* ... */}
      </form>
    </div>
  );
}

Distinguishing error types

The errorText is just a string, so distinguish error types via prefixes or codes:

// Backend
uiMessageStreamOptions: {
  onError: (error) => {
    if (error.message.includes("rate limit")) return "RATE_LIMIT: Please wait and try again.";
    if (error.message.includes("context_length")) return "CONTEXT_TOO_LONG: Start a new chat.";
    return "UNKNOWN: Something went wrong.";
  },
},

// Frontend
{error?.message.startsWith("RATE_LIMIT") && <RateLimitNotice />}
{error?.message.startsWith("CONTEXT_TOO_LONG") && <NewChatPrompt />}

For richer error structures, use chat.response.write() with a custom data-error part type. This lets you ship structured error metadata (codes, retry hints, etc.) instead of stringly-typed messages.

Errors from `accessToken` / `startSession`

If your accessToken or startSession callback throws (auth failure, DB write failure, network error), the rejection surfaces through useChat’s error state — same as a stream error. The transport doesn’t retry the callback automatically; the customer is responsible for handling it.

const transport = useTriggerChatTransport({
  task: "my-chat",
  accessToken: async ({ chatId }) => {
    try {
      return await mintChatAccessToken(chatId);
    } catch (err) {
      // Customer's server action failed (e.g. user lost auth).
      // Re-throw to surface as a useChat error, or return a sentinel
      // your UI can detect and prompt re-auth.
      throw new Error(`AUTH_REFRESH: ${err.message}`);
    }
  },
  startSession: ({ chatId, clientData }) =>
      startChatSession({ chatId, clientData }),
});

startSession failures most commonly mean the customer’s authorization layer rejected the request (no plan, quota exceeded, user not allowed to chat with this agent). The customer’s server should produce a meaningful error message; the transport propagates it verbatim to useChat’s error state.

Run-level retries

chat.agent defaults to retry: { maxAttempts: 1 }. Turn errors are handled within the conversation, so another message can succeed in the same run. If you configure oomMachine, the agent uses up to 2 attempts and retries an out-of-memory failure on that machine. This doesn’t enable retries for ordinary provider or tool errors. Use the AI SDK’s provider retry settings for transient model-call failures. After a turn has failed, let the user send another message or call regenerate(). Retrying a conversation can repeat tool side effects, so use idempotency keys for writes.

Best practices

Always set uiMessageStreamOptions.onError to sanitize stream errors before they reach the user.
Persist messages in onTurnStart so a mid-stream failure still leaves the user’s message visible.
Use onTurnComplete to mark turn status in your DB (ok / errored / stopped).
Don’t throw raw errors with internal details in hooks — catch, log, then throw a sanitized user-facing message.
Provide an undo or retry affordance in the UI when errors occur.
Use onFailure for run-level monitoring (Sentry, monitoring dashboards).
For known transient errors (rate limits, network), consider a fallback model inside run() instead of failing the turn.

`ChatChunkTooLargeError`

A specific run-failing error worth flagging on its own. Anything written through the chat output is one record on the underlying realtime stream, capped at ~1 MiB per record. A single chunk over the cap throws ChatChunkTooLargeError (named export from @trigger.dev/sdk). The most common trigger is a tool whose result object is large enough to overflow as one tool-output-available chunk. The error carries chunkType, chunkSize, and maxSize. Catch with the isChatChunkTooLargeError guard and route oversized values out-of-band. See Large payloads in chat.agent for the ID-reference pattern that works around the cap, plus guidance on transient data parts and out-of-band logging.

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

Error layers at a glance

Stream errors mid-turn

Hook and turn errors

Catching errors in your own hooks

Catching errors inside `run()`

Saving error state to your DB

Using `onTurnComplete`

Using the standard `onFailure` task hook

Recovery patterns

Pattern 1: Undo to last successful response

Pattern 2: Retry the last message

Pattern 3: Save partial responses

Pattern 4: Retry with another model

What gets written to the stream on error

Frontend error handling

Showing the error to the user

Distinguishing error types

Errors from `accessToken` / `startSession`

Run-level retries

Best practices

`ChatChunkTooLargeError`

See also

​Error layers at a glance

​Stream errors mid-turn

​Hook and turn errors

​Catching errors in your own hooks

​Catching errors inside run()

​Saving error state to your DB

​Using onTurnComplete

​Using the standard onFailure task hook

​Recovery patterns

​Pattern 1: Undo to last successful response

​Pattern 2: Retry the last message

​Pattern 3: Save partial responses

​Pattern 4: Retry with another model

​What gets written to the stream on error

​Frontend error handling

​Showing the error to the user

​Distinguishing error types

​Errors from accessToken / startSession

​Run-level retries

​Best practices

​ChatChunkTooLargeError

​See also

Error layers at a glance

Stream errors mid-turn

Hook and turn errors

Catching errors in your own hooks

Catching errors inside `run()`

Saving error state to your DB

Using `onTurnComplete`

Using the standard `onFailure` task hook

Recovery patterns

Pattern 1: Undo to last successful response

Pattern 2: Retry the last message

Pattern 3: Save partial responses

Pattern 4: Retry with another model

What gets written to the stream on error

Frontend error handling

Showing the error to the user

Distinguishing error types

Errors from `accessToken` / `startSession`

Run-level retries

Best practices

`ChatChunkTooLargeError`

See also