# Stack Trace

Displays a failed tool call and its stack frames.

Source: https://webjs.dev/ui/docs/ai-elements/stack-trace

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, FileCodeIcon, LayersIcon, TerminalIcon } from '#lib/ui/lucide.ts';

const question = 'Reset the database and seed it.';
const answer =
  'The migrations ran, but the seed failed in seedUsers. One fixture has no profile, so profile.email is undefined.';

const RESET_OUTPUT = `Database reset successful

The following migrations have been applied:

migrations/
  └─ 20260912_init/
  └─ 20260920_add_profiles/`;

const STACK = `TypeError: Cannot read properties of undefined (reading 'email')
    at seedUsers (prisma/seed.ts:27:34)
    at main (prisma/seed.ts:51:9)
    at Module._compile (node:internal/modules/cjs/loader:1554:14)
    at Object.transformer (node_modules/tsx/dist/register.cjs:3:1104)
    at Module.load (node:internal/modules/cjs/loader:1289:32)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)`;

function parseFrame(line: string) {
  const match = line.match(/^at (.+) \((.+):(\d+):(\d+)\)$/);
  return {
    line,
    name: match?.[1],
    file: match?.[2],
    lineNumber: match?.[3],
    internal: line.includes('node_modules') || line.includes('node:'),
  };
}

const chevron = () => html`<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform [[open]>summary>&]:rotate-90')}>${ChevronRightIcon()}</span>`;

// A failed command: the error is the title, and the content repeats it above
// the frames, with your own frames as links and the rest folded away.
function StackTrace(stack: string) {
  const [error, ...lines] = stack.split('\n').map((line) => line.trim());
  const frames = lines.map(parseFrame);
  const appFrames = frames.filter((frame) => !frame.internal);
  const internalFrames = frames.filter((frame) => frame.internal);

  return html`
    <details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        <span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Failed: ${error}</span>
        </span>
        ${chevron()}
      </summary>
      <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-2')}>
        <p class="font-mono text-xs text-destructive">${error}</p>
        <div data-slot="trace" class=${traceClass()}>
          ${appFrames.map((frame) => html`
            <a href=${'#' + frame.file + ':' + frame.lineNumber}>
              <span data-slot="trace-line" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileCodeIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>${frame.name} in ${frame.file}:${frame.lineNumber}</span>
              </span>
            </a>
          `)}
          <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
            <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
              <span data-slot="trace-line" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${LayersIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>${internalFrames.length} framework frames</span>
              </span>
              ${chevron()}
            </summary>
            <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
              <ol class="flex flex-col gap-1 overflow-x-auto rounded-md bg-muted p-3 font-mono text-xs">
                ${internalFrames.map((frame) => html`<li class="whitespace-nowrap">${frame.line}</li>`)}
              </ol>
            </div>
          </details>
        </div>
      </div>
    </details>
  `;
}

// The conversation once the reply has finished streaming.
export default function StackTraceDemo() {
  return html`
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
          <div data-slot="trace" class=${traceClass()}>
            <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
              <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
                <span data-slot="trace-line" class=${traceLineClass()}>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>Ran pnpm prisma migrate reset --skip-seed</span>
                </span>
                ${chevron()}
              </summary>
              <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
                <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
                  <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${RESET_OUTPUT}</code></pre>
                </div>
              </div>
            </details>
            ${StackTrace(STACK)}
          </div>
          <p>${answer}</p>
        </div>
      </div>
      <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
        Replay
      </button>
    </div>
  `;
}
```

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 a trace, with a trace collapsible for the frames.

## Installation

Stack Trace is built with the [Trace](https://webjs.dev/ui/docs/components/trace) and [Code Block](https://webjs.dev/ui/docs/components/code-block) components.

```bash
npx @webjsdev/ui add trace code-block
```

### Install the following dependencies:

```bash
npx @webjsdev/ui add code-block
```

### Copy and paste the following code into your project.

````ts title="components/ui/trace.ts"
/**
 * Trace: a vertical timeline of steps (a tool call, a reasoning step, a
 * deploy stage), each with an icon on a connecting line, a title and an
 * optional collapsible detail. Tier-1 class helper; compose with plain
 * elements and `<details>` for the collapsible part.
 *
 * shadcn parity:
 *   Trace                       → traceClass()
 *   TraceLine / TraceIcon       → traceLineClass() / traceIconClass()
 *   TraceTitle / TraceDescription
 *                               → traceTitleClass() / traceDescriptionClass()
 *   TraceCollapsible / TraceCollapsibleTrigger / TraceCollapsibleContent
 *                               → <details> / <summary> / a div, with the
 *                                 trace collapsible helpers
 *
 * shadcn has no new-york version of this component, so its look in the
 * default style is shadcn's vega style, the classic shadcn look.
 *
 * A11y (required for accessible output): a trace is an ordered list of steps,
 * so render it as `<ol>` with each step an `<li>`. A step's status must be in
 * text, not only in the icon colour ("Failed", "Done"), and a decorative icon
 * takes `aria-hidden="true"`. A collapsible step is a native `<details>` with a
 * `<summary>`, which carries the expanded state by itself.
 *
 * Design tokens used: --border, --muted-foreground, --foreground.
 *
 * @example
 * ```html
 * <ol class=${traceClass()} data-slot="trace">
 *   <li class=${traceLineClass()} data-slot="trace-line">
 *     <span class=${traceTitleClass()} data-slot="trace-title">Fetched the issue</span>
 *   </li>
 * </ol>
 * ```
 */

/** Set `data-slot="trace"` on the element. */
export function traceClass(): string {
  return 'gap-2 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:focus-visible:ring-3 *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50 flex w-full min-w-0 flex-col *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:text-start *:has-[>[data-slot=trace-line]]:outline-none';
}

/** Set `data-slot="trace-line"` on the element. */
export function traceLineClass(): string {
  return 'gap-2 text-sm flex w-fit max-w-full min-w-0 items-center text-muted-foreground transition-colors in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground data-[status=error]:text-destructive data-[status=error]:in-[a:hover,button:hover]:text-destructive data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer';
}

/** Set `data-slot="trace-icon"` on the element. */
export function traceIconClass(): string {
  return "size-4 [&_svg:not([class*='size-'])]:size-4 [[data-slot=trace-title]~&]:-ms-1 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none";
}

/** Set `data-slot="trace-title"` on the element. */
export function traceTitleClass(): string {
  return 'min-w-0 truncate motion-reduce:shimmer-none';
}

/** Set `data-slot="trace-description"` on the element. */
export function traceDescriptionClass(): string {
  return 'shrink-0 text-muted-foreground/70 tabular-nums';
}

/** Set `data-slot="trace-collapsible"` on the element. */
export function traceCollapsibleClass(): string {
  return 'flex w-full min-w-0 flex-col';
}

/** Set `data-slot="trace-collapsible-trigger"` on the element. */
export function traceCollapsibleTriggerClass(): string {
  return 'gap-1 rounded-md focus-visible:ring-3 focus-visible:ring-ring/50 group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center text-start text-muted-foreground transition-colors outline-none hover:text-foreground has-[[data-status=error]]:text-destructive';
}

/** Set `data-slot="trace-collapsible-content"` on the element. */
export function traceCollapsibleContentClass(): string {
  return 'mt-2 mb-1 ms-[calc(--spacing(2)-1px)] border-s pe-1 ps-4 leading-relaxed min-w-0 wrap-break-word text-muted-foreground';
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import {
  traceClass,
  traceCollapsibleClass,
  traceCollapsibleContentClass,
  traceCollapsibleTriggerClass,
  traceIconClass,
  traceLineClass,
  traceTitleClass,
} from '#components/ui/trace.ts';
```

```ts
const [error, ...frames] = stack.split('\n').map((line) => line.trim());

html`<div data-slot="trace" class=${traceClass()}>
  <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
    <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
      <span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
          ${CircleXIcon()}
        </span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Failed: ${error}</span>
      </span>
      <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>
        ${ChevronRightIcon()}
      </span>
    </summary>
    <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
      <div class="flex flex-col gap-2 rounded-md bg-muted p-3 font-mono text-xs">
        <p class="text-destructive">${error}</p>
        <ol>
          ${frames.map((frame) => html`
            <li class=${frame.includes('node_modules') ? '' : 'text-foreground'}>${frame}</li>
          `)}
        </ol>
      </div>
    </div>
  </details>
</div>`
```

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.

## Frame Links

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.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, CircleXIcon, FileCodeIcon, LayersIcon } from '#lib/ui/lucide.ts';

const STACK = `TypeError: Cannot read properties of undefined (reading 'total')
    at formatInvoice (app/lib/billing.ts:42:31)
    at InvoiceRow (app/components/invoice-row.tsx:18:12)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:14985:18)
    at beginWork (node_modules/react-dom/cjs/react-dom.development.js:19049:16)
    at performUnitOfWork (node_modules/react-dom/cjs/react-dom.development.js:22776:12)
    at workLoopSync (node_modules/react-dom/cjs/react-dom.development.js:22707:5)`;

function parseFrame(line: string) {
  const match = line.match(/^at (.+) \((.+):(\d+):(\d+)\)$/);
  return {
    line,
    name: match?.[1],
    file: match?.[2],
    lineNumber: match?.[3],
    internal: line.includes('node_modules'),
  };
}

const [error, ...lines] = STACK.split('\n').map((line) => line.trim());
const frames = lines.map(parseFrame);
const appFrames = frames.filter((frame) => !frame.internal);
const internalFrames = frames.filter((frame) => frame.internal);

const chevron = () => html`<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform [[open]>summary>&]:rotate-90')}>${ChevronRightIcon()}</span>`;

export default function StackTraceFrames() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleXIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Failed: ${error}</span>
          </span>
          ${chevron()}
        </summary>
        <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-2')}>
          <p class="font-mono text-xs text-destructive">${error}</p>
          <div data-slot="trace" class=${traceClass()}>
            ${appFrames.map((frame) => html`
              <a href=${'#' + frame.file + ':' + frame.lineNumber}>
                <span data-slot="trace-line" class=${traceLineClass()}>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileCodeIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>${frame.name} in ${frame.file}:${frame.lineNumber}</span>
                </span>
              </a>
            `)}
            <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
              <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
                <span data-slot="trace-line" class=${traceLineClass()}>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${LayersIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>${internalFrames.length} framework frames</span>
                </span>
                ${chevron()}
              </summary>
              <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
                <ol class="flex flex-col gap-1 overflow-x-auto rounded-md bg-muted p-3 font-mono text-xs">
                  ${internalFrames.map((frame) => html`<li class="whitespace-nowrap">${frame.line}</li>`)}
                </ol>
              </div>
            </details>
          </div>
        </div>
      </details>
    </div>
  `;
}
```

## AI SDK

When a tool throws, its part is `output-error`, and by default `errorText` is only the error message, with no frames. Where your `'use server'` action streams the parts (see [AI SDK](https://webjs.dev/ui/docs/helpers/ai-sdk)), catch the tool's error and put `error.stack` in the part yourself.

```ts title="modules/chat/utils/error-text.server.ts"
function errorText(error: unknown) {
  if (!(error instanceof Error)) return String(error);
  return process.env.NODE_ENV === 'production' ? error.message : (error.stack ?? error.message);
}
```

A stack shows file paths from your server, so only send it in development, as above. A WebJs action that throws in production already sends the client a generic message and a digest, never the stack.

```ts
function toolRow(part: ToolPart) {
  if (part.state === 'output-error') {
    const [error, ...frames] = part.errorText.split('\n').map((line) => line.trim());
    return html`<details data-slot="trace-collapsible" class=${traceCollapsibleClass()}>…</details>`;
  }
  // …
}
```

Map the other tool states as in [Tool](https://webjs.dev/ui/docs/ai-elements/tool#states).

## Migrating from AI SDK Elements

If you used Stack Trace from [AI SDK Elements](https://elements.ai-sdk.dev), its wrapper lives in `components/ai-elements/stack-trace.tsx`. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:

| AI SDK Elements | WebJs UI |
| --- | --- |
| `StackTrace` | A trace with a trace collapsible. Its open state is the `<details>` element's own `open`, and the parsing stays yours. |
| `StackTraceHeader` | The collapsible's `<summary>`, holding a trace line with `data-status="error"` and a trace icon. |
| `StackTraceError` | A trace title, like "Failed: TypeError: …". Keep the error type and message as spans inside it. |
| `StackTraceContent` | The trace collapsible content. |
| `StackTraceFrames` | The frames as a list in a muted, monospace block, with the frames from `node_modules` dimmed and your own frames as links. |
| `StackTraceExpandButton` | Nothing, since the whole line opens the frames. |
| `StackTraceActions, StackTraceCopyButton` | Buttons next to the `<summary>`, not inside it, since a button cannot sit inside a trigger. |

## API Reference

See [Trace](https://webjs.dev/ui/docs/components/trace#api-reference).
