# Stack Trace

> A crash shown the way a developer reads it. Your code comes first, framework frames fold away and every cause is listed in order.

Canonical: https://hextaui.com/blocks/stack-trace
Last updated: 2026-10-29

## Overview

When an agent’s command, tool call or test fails, the useful part of the error is buried in fifty lines of framework internals. Stack Trace puts the error type and message first, shows your own frames in full contrast with file, line and column, and folds every run of framework frames into one quiet row like “8 framework frames · next”.

parseStackTrace reads V8 stacks from Node, Chrome, Bun and Deno, Firefox and Safari stacks, Vitest frames with the code under them and Python tracebacks, including chained causes from [cause], Caused by: and Python’s “direct cause” and “during handling” sections. It classifies node_modules, node:internal, Next.js internals, site-packages and the standard library as non-app code, and turns file:// and webpack-internal paths into readable project paths. Lines it doesn’t recognise are kept, never dropped.

The frame where your code failed can show its source with the failing line highlighted, using Code Block. Long messages clamp with Show more, Copy gives back the original text, and frames open in your editor through getFrameHref or onFrameClick. The compact variant is a single “Failed: TypeError: …” line for a failed tool call that opens into the same frames.

## Installation

### Step 1: Get HextaUI Pro

One payment unlocks every block, including future ones. [See pricing](https://hextaui.com/pricing).

### Step 2: Add the Pro registry to components.json

```json title="components.json"
{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}
```

### Step 3: Add your token

Create a token on your [account page](https://hextaui.com/account) and put it in `.env.local` as `HEXTAUI_PRO_TOKEN`.

### Step 4: Add the block

```bash
npx shadcn@latest add @hextaui-pro/stack-trace
```

## Usage

### From a log

Pass the raw text from a terminal, a log or a tool result. getEditorHref turns frames into vscode:// or cursor:// links, and Ask to fix hands you the parsed error to send back to the agent.

```tsx
"use client"

import { getEditorHref } from "@/components/blocks/stack-trace/parse-stack-trace"
import { StackTrace } from "@/components/blocks/stack-trace/stack-trace"

export function CrashReport({
  log,
  onAsk,
}: {
  log: string
  onAsk: (prompt: string) => void
}) {
  return (
    <StackTrace
      trace={log}
      getFrameHref={(frame) =>
        frame.kind === "app"
          ? getEditorHref(frame, { editor: "cursor", root: "/Users/me/acme" })
          : undefined
      }
      onAskToFix={(error) =>
        onAsk(`Fix this ${error.type}: ${error.message}\n\n${error.raw}`)
      }
    />
  )
}
```

### With the AI SDK

A tool that throws ends in the output-error state with errorText. Render it as a compact StackTrace inside the failed ToolCall, so the step reads as one line until someone opens it.

```tsx
"use client"

import { useChat } from "@ai-sdk/react"
import {
  getToolName,
  isToolUIPart,
  type DynamicToolUIPart,
  type ToolUIPart,
  type UIMessage,
} from "ai"

import type { ToolCallProps } from "../tool-calls/tool-call"
import { ToolCalls } from "../tool-calls/tool-group"
import { getToolPartStatus } from "../tool-calls/tool-part"
import { getEditorHref } from "@/components/blocks/stack-trace/parse-stack-trace"
import { StackTrace } from "@/components/blocks/stack-trace/stack-trace"

type ToolPart = ToolUIPart | DynamicToolUIPart

function toCall(
  part: ToolPart,
  streaming: boolean,
  onAsk: (text: string) => void
): ToolCallProps {
  const input = (part.input ?? {}) as { command?: string }
  const failed = part.state === "output-error"
  return {
    id: part.toolCallId,
    kind: getToolName(part) === "runCommand" ? "run" : "other",
    name: getToolName(part),
    subject: input.command,
    status: getToolPartStatus(part, { stopped: !streaming }),
    defaultOpen: failed ? true : undefined,
    content: failed ? (
      <StackTrace
        variant="compact"
        trace={part.errorText}
        getFrameHref={(frame) =>
          getEditorHref(frame, { root: process.env.NEXT_PUBLIC_PROJECT_ROOT })
        }
        onAskToFix={(error) =>
          onAsk(
            `The ${getToolName(part)} call failed with ${error.type}: ${error.message}. Fix it.`
          )
        }
      />
    ) : undefined,
  }
}

function AssistantMessage({
  message,
  streaming,
  onAsk,
}: {
  message: UIMessage
  streaming: boolean
  onAsk: (text: string) => void
}) {
  const calls = message.parts
    .filter(isToolUIPart)
    .map((part) => toCall(part, streaming, onAsk))
  return calls.length ? <ToolCalls calls={calls} /> : null
}

export function Chat() {
  const { messages, status, sendMessage } = useChat()
  const busy = status === "submitted" || status === "streaming"

  return messages.map((message, index) =>
    message.role === "assistant" ? (
      <AssistantMessage
        key={message.id}
        message={message}
        streaming={busy && index === messages.length - 1}
        onAsk={(text) => sendMessage({ text })}
      />
    ) : null
  )
}
```

### In a Next.js error boundary

parseError reads an Error object, including its name, message and cause chain. Show the trace in development and a plain message in production.

```tsx
"use client"

import { Button } from "@/components/ui/button"

import { parseError } from "@/components/blocks/stack-trace/parse-stack-trace"
import { StackTrace } from "@/components/blocks/stack-trace/stack-trace"

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <main className="mx-auto flex w-full max-w-2xl flex-col gap-4 p-6">
      {process.env.NODE_ENV === "development" ? (
        <StackTrace label="Crashed" trace={parseError(error)} />
      ) : (
        <p className="text-sm text-muted-foreground">Something went wrong.</p>
      )}
      <Button variant="outline" className="self-start" onClick={reset}>
        Try again
      </Button>
    </main>
  )
}
```

### Just the frames

parseStackTrace and StackFrames work on their own, for example to show a short stack under each failed test.

```tsx
"use client"

import { parseStackTrace } from "@/components/blocks/stack-trace/parse-stack-trace"
import { StackFrames } from "@/components/blocks/stack-trace/stack-frames"

export function FailedTest({ name, stack }: { name: string; stack: string }) {
  const error = parseStackTrace(stack, { root: "/Users/me/acme" })

  return (
    <div className="flex flex-col gap-1">
      <p className="text-sm">
        {name}: <span className="text-muted-foreground">{error.message}</span>
      </p>
      <StackFrames frames={error.frames} showSource={false} />
    </div>
  )
}
```

## Anatomy

The parts you compose, from the outside in.

| Part | Description |
| --- | --- |
| `StackTrace` | The error: type, message, actions, frames and causes. Default is a card; compact is one line that expands. |
| `StackFrames` | The frame list on its own, with folded framework frames and the source excerpt. |
| `parseStackTrace, parseError` | Pure parsers that turn text or an Error object into a ParsedStackTrace. |
| `getEditorHref` | Builds a vscode://, cursor://, windsurf:// or zed:// link for a frame. |

## API reference

### StackTrace

Also accepts every div prop except children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trace` | `string \| ParsedStackTrace` | – | The raw stack text, or a trace you parsed and enriched yourself. |
| `variant` | `"default" \| "compact"` | `"default"` | compact renders one “Failed: …” line that opens into the frames, for use inside a ToolCall. |
| `label` | `string` | `"Failed"` | The status word before the error type, such as “Crashed” or “Test failed”. |
| `root` | `string` | – | Project root, stripped from absolute paths. Found from node_modules or .venv when left out. |
| `getFrameHref` | `(frame: StackFrame) => string \| undefined` | – | Turns a frame into a link, for example with getEditorHref. |
| `onFrameClick` | `(frame: StackFrame, event: MouseEvent) => void` | – | Called when a frame is clicked. Call event.preventDefault() to handle links yourself. |
| `onAskToFix` | `(trace: ParsedStackTrace) => void` | – | Shows Ask to fix and receives the parsed error. |
| `askLabel` | `string` | `"Ask to fix"` | Label for the Ask to fix button. |
| `showSource` | `boolean` | `true` | Show source lines under frames, and the excerpt for your top frame. |
| `fold` | `boolean` | `true` | Fold runs of two or more framework or internal frames. |
| `messageLines` | `number` | `3` | Lines of message shown before Show more. |
| `open` | `boolean` | – | Controlled open state of the compact variant. |
| `defaultOpen` | `boolean` | `false` | Whether the compact variant starts open. |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the compact variant opens or closes. |

### StackFrames

Also accepts every ol prop except children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `frames` | `StackFrame[]` | – | Frames from parseStackTrace, innermost first. |
| `fold` | `boolean` | `true` | Fold runs of non-app frames. |
| `showSource` | `boolean` | `true` | Show source lines and the top frame’s excerpt. |
| `getFrameHref` | `(frame: StackFrame) => string \| undefined` | – | Turns a frame into a link. |
| `onFrameClick` | `(frame: StackFrame, event: MouseEvent) => void` | – | Called when a frame is clicked. |

### parseStackTrace(text, options)

Returns a ParsedStackTrace. parseError(error, options) does the same for an Error object and its cause.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | – | A stack, a traceback or raw log output around one. |
| `options.root` | `string` | – | Project root to strip from absolute paths. |
| `options.classify` | `(frame: StackFrame) => StackFrameKind \| undefined` | – | Override the kind of a frame, for example to treat a vendored folder as framework code. |

### ParsedStackTrace

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` | – | Error type, such as TypeError or billing.plans.PlanNotFound. |
| `message` | `string` | – | The message, which can span several lines. |
| `frames` | `StackFrame[]` | – | Innermost first for every language, so frames[0] is where it threw. |
| `raw` | `string` | – | The original text, used by Copy. |
| `language` | `"javascript" \| "python"` | – | Which format was parsed. |
| `code` | `string` | – | Error code, such as ERR_MODULE_NOT_FOUND or ECONNREFUSED. |
| `details` | `string` | – | Extra properties Node prints after the frames, such as errno and syscall. |
| `preamble` | `string` | – | Log lines that came before the error. |
| `cause` | `ParsedStackTrace` | – | The next error in the chain, with relation set to cause or context. |

### StackFrame

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"app" \| "framework" \| "internal"` | – | Your code, a dependency, or the runtime itself. |
| `fn` | `string` | – | Function name. Undefined for anonymous functions, which show only their location. |
| `file` | `string` | – | Readable path relative to the project, such as app/api/users/route.ts. |
| `path` | `string` | – | The location as reported, with file:// and webpack prefixes removed. Absolute when the stack had one. |
| `line, column` | `number` | – | Position in the file. |
| `package` | `string` | – | Package a non-app frame belongs to, such as next or fastapi. |
| `source, sourceStart` | `string, number` | – | Source lines and the number of the first one. Several lines show as an excerpt. |
| `raw` | `string` | – | The original line. Lines the parser doesn’t recognise only have raw. |

### getEditorHref(frame, options)

Returns undefined for frames without a file on disk.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options.editor` | `"vscode" \| "cursor" \| "windsurf" \| "zed"` | `"vscode"` | The URL scheme to use. |
| `options.root` | `string` | – | Joined with relative paths, such as those from webpack-internal frames. |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves through the actions, Show more, frame links and folded frame rows. |
| `Enter` `Space` | Opens or closes folded frames, or the compact line. |
| `Enter` | Opens a frame link in your editor. |

## Accessibility

- Frames are an ordered list, so screen readers announce how many there are and the position of each.
- Folded rows are buttons with aria-expanded, and folded frames stay findable with the browser’s find in page, which opens the fold.
- The default view is a group named by its status and error type, and each cause is a section named “Caused by …”.
- Status is never color alone: the failure is written out as text next to its icon, and Copy announces “Copied”.

## Built with

The free HextaUI components Stack Trace is made from. Each one installs on its own.

- [Button](https://hextaui.com/docs/button) - Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- [Card](https://hextaui.com/docs/card) - A surface for grouping content, with three variants, edge-to-edge media, concentric radii and whole-card links.
- [Collapsible](https://hextaui.com/docs/collapsible) - A panel that shows and hides with height motion you can reverse mid-way, without jumping the layout.
- [Tooltip](https://hextaui.com/docs/tooltip) - A short hint on hover or keyboard focus that opens after a brief rest, switches instantly between neighbours and shows shortcuts.

## Code

5 files, added to components/blocks/stack-trace.
