126k
New

Stack Trace

PreviousNext

Displays a failed tool call and its stack frames.

Base UIReact AriaRadix UI
Radix UI
Reset the database and seed it.

TypeError: Cannot read properties of undefined (reading 'email')

seedUsers in prisma/seed.ts:27main in prisma/seed.ts:51

The migrations ran, but the seed failed in seedUsers. One fixture has no profile, so profile.email is undefined.

"use client"

import { useChat } from "@ai-sdk/react"

Stack Trace is a line for a tool call that failed. The error is the title, like "Failed: TypeError". Open it for the stack frames, which can link to the file and line.

Stack Trace is built with Trace with a TraceCollapsible for the frames.

Installation

Stack Trace is built with the Trace and Code Block components.

pnpm dlx shadcn@latest add trace code-block

Usage

import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace"
const [error, ...frames] = stack.split("\n").map((line) => line.trim())
 
<Trace>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine status="error">
        <TraceIcon>
          <CircleXIcon />
        </TraceIcon>
        <TraceTitle>Failed: {error}</TraceTitle>
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>
      <div className="flex flex-col gap-2 rounded-md bg-muted p-3 font-mono text-xs">
        <p className="text-destructive">{error}</p>
        <ol>
          {frames.map((frame, index) => (
            <li
              key={index}
              className={
                frame.includes("node_modules") ? undefined : "text-foreground"
              }
            >
              {frame}
            </li>
          ))}
        </ol>
      </div>
    </TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

The title truncates, so repeat the full error at the top of the content. Frames from node_modules stay muted, so your own frames stand out.

Turn your own frames into links that open the file at the line. Fold the framework frames into a collapsible line of their own, so the frames you can fix come first.

TypeError: Cannot read properties of undefined (reading 'total')

formatInvoice in app/lib/billing.ts:42InvoiceRow in app/components/invoice-row.tsx:18
import { CircleXIcon, FileCodeIcon, LayersIcon } from "lucide-react"

import {

AI SDK

When a tool throws, its part is output-error. By default errorText is only the error message, with no frames. Return error.stack from onError in toUIMessageStreamResponse to send them.

app/api/chat/route.ts
return result.toUIMessageStreamResponse({
  onError: (error) =>
    error instanceof Error ? (error.stack ?? error.message) : String(error),
})

A stack shows file paths from your server, so only send it in development.

if (part.state === "output-error") {
  const [error, ...frames] = part.errorText
    .split("\n")
    .map((line) => line.trim())
 
  return <TraceCollapsible>…</TraceCollapsible>
}

Map the other tool states as in Tool.

Migrating from AI SDK Elements

If you added Stack Trace from AI SDK Elements, your project has a components/ai-elements/stack-trace.tsx wrapper. Paste this prompt into your coding agent to rebuild it on Trace. Every export keeps its name and props, so the code that uses it keeps working.

Prompt
Migrate components/ai-elements/stack-trace.tsx from AI SDK Elements to the shadcn/ui Trace component.
 
Keep every export, with the same name and props, so the code that imports it keeps working. Only change how each part renders.
 
1. Install Trace: npx shadcn@latest add trace
2. Read https://ui.shadcn.com/docs/ai-elements/radix/stack-trace.md and build Stack Trace the same way.
3. Rebuild each part:
   - StackTrace renders a Trace with a TraceCollapsible. Keep trace, open, defaultOpen, onOpenChange and onFilePathClick, and the parsing.
   - StackTraceHeader renders a TraceCollapsibleTrigger with a TraceLine with status="error" and a TraceIcon.
   - StackTraceError renders a TraceTitle, like "Failed: TypeError: …". Keep StackTraceErrorType and StackTraceErrorMessage as spans inside it.
   - StackTraceContent renders a TraceCollapsibleContent.
   - StackTraceFrames renders the frames as a list in a muted, monospace block. Dim the frames from node_modules, and keep the file path buttons.
   - StackTraceExpandButton renders nothing, since the whole line opens the frames.
   - Buttons cannot sit inside a trigger. Render StackTraceActions and StackTraceCopyButton next to the TraceCollapsibleTrigger, not inside it.
4. Remove the imports the file no longer uses.
5. Run the type checker and fix any errors.

API Reference

See Trace.