# Run Error

A failed run: which step threw, how many attempts are left, retry or resume.

- Category: AI & Agents
- Page: https://wunderui.com/components/run-error
- Tier: Core and Pro

## Install

Run Error ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { RunError } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { RunError } from "@wunderui/react"

export function Failed({ error, resume, cancel }: { error: Error; resume: () => void; cancel: () => void }) {
  return (
    <RunError
      message="The invoice API is limiting requests. Wait a minute, then resume."
      failedStep="fetch_invoices"
      attempt={2}
      maxAttempts={3}
      detail={error.stack}
      onRetryFrom={resume}
      onCancel={cancel}
    />
  )
}
```

Expected result: You should see a red card with the message, the failure line, a Show error detail button, a filled Resume from this step and Cancel run. Press the detail button to open the trace.

## When to use

### Use Run Error for

- A run that stopped, with the step that failed and the attempts that are left
- Offering the next move: resume from the failed step, run again or cancel
- Keeping the stack trace and the error ID one click away, not in the headline

### Use something else

- [Terminal Output](https://wunderui.com/components/terminal-output) for a failed command with its exit code and output
- [Plan Step](https://wunderui.com/components/plan-step) for one failed row in a plan, with a Retry button on the row
- [Alert](https://wunderui.com/components/alert) for a failed tool call or any other short notice, with the way forward next to it
- [Run Timeline](https://wunderui.com/components/run-timeline) for every step of the run, including the one that failed

## Keyboard

The card has one disclosure and up to three buttons, all native buttons, so the browser provides focus and activation. The card itself is not focusable.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus through the error detail button, then, when the detail is open, the Copy button and the code area (it scrolls with the arrow keys), then the actions in order. The closed detail is `inert`, so Tab skips it. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | On the detail button, opens or closes the detail and flips `aria-expanded`. On an action, presses it. |

## Behavior

What the card announces, which buttons it shows and what it keeps for itself.

- **Announcement:** The card is an alert: a screen reader reads it when it is added to the page, not when it is there at load. Mount it when the run fails, and replace it to show a second failure.
- **Attempts:** Attempt and max attempts together write Attempt n of m. At or above the maximum the line adds no retries left in red; either number alone writes nothing.
- **Actions:** Each button appears only when its handler is passed, and Cancel run is always plain. The card does not hide a button at the last attempt, so leave the handler out.
- **Detail:** The detail opens in a Code Block behind a disclosure button. The Code Block names its language (text by default), has its own Copy button and takes focus so long lines can scroll.
- **Error ID:** There is no prop for an error ID or a report link. Write the ID as the last line of the detail so Copy picks it up, or put a Copy ID button and a link under the card.
- **State:** The only state the card keeps is whether the detail is open. It never removes itself: you decide whether the card stays, changes or goes away.
- **Focus:** The card does not take focus when it appears. If a button takes the card away, focus is lost with it; move focus to the status line that replaces it.
- **Motion:** The detail opens over the base duration and the chevron turns over the fast duration.
- **Reduced motion:** With reduced motion the detail and the chevron change at once. The text, buttons and red tint stay the same.

## Anatomy

- `RunError`: A card with a red tint, a 1 px red border, a 16 px radius and 16 px padding. It is an alert, so it is announced when it appears.
- `Icon`: A 16 px warning triangle in the red text colour.
- `Message`: The message in 14 px semibold red text. It says what happened and what to do.
- `Failure line`: Failed at and the failed step in monospace, then Attempt n of m when both counts are given. At the last attempt it adds no retries left in red.
- `Error detail`: A button that reads Show error detail or Hide error detail and opens a Code Block with the detail. It starts closed unless you open it by default, and the Code Block has its own Copy button.
- `Actions`: Resume from this step, Run again and Cancel run, each only when its handler is passed. Resume from this step is the filled button, or Run again when there is no resume handler; Cancel run is plain.

## Best practices

### When to use

- Use RunError when a whole run stops. For a failed command use Terminal Output, for one failed row in a plan use Plan Step, and for a failed tool call in a chat use an Alert.

### Do

- Say what happened and what to do in plain words, for example that the API is limiting requests and people should wait a minute, then resume. Name the failed step separately.
- Pass the resume handler when the steps before the failure are kept. Resume from this step then becomes the filled button and Run again turns plain.
- Put the stack trace, the raw response and the error ID in the detail, one line each. The headline stays short and the Code Block copies the lot.
- Mount the card when the run fails and not before, so it is announced. When a button takes the card away, move focus to the status line that replaces it.

### Don't

- Don't pass a retry handler once the attempts are used up. The card marks no retries left but still draws every button you give it.
- Don't put a status code, a stack trace or the word Error alone in the message. Those belong in the detail.
- Don't use it for a mistake in a form field. A field error belongs next to the field.

## API reference

### RunError

| Prop | Type | Default | Description |
|---|---|---|---|
| message* | React.ReactNode |  | The headline: what happened and what to do, in one or two sentences. Any node. |
| actions | React.ReactNode |  | Extra actions appended to the row of buttons. |
| attempt | number |  | The attempt that just failed, counting from 1. Needs `maxAttempts` to be shown. |
| cancelLabel | string | "Cancel run" | Label of the cancel button. Default `Cancel run`. |
| className | string |  | Extra classes for the card, for example `w-full`. |
| defaultOpen | boolean | false | Opens the error detail on the first render. It is only the starting state; the person can still close it. |
| description | React.ReactNode |  | Text under the message, for a human explanation of the failure. |
| detail | string |  | A stack trace, a raw error body or an error ID, as plain text. It sits in a Code Block behind the Show error detail button. |
| detailLanguage | string | "text" | The language label of the Code Block. Default `text`. |
| failedStep | React.ReactNode |  | The step that threw, such as `fetch_invoices`. Shown after `Failed at` in monospace. |
| maxAttempts | number |  | How many attempts the step gets. At or above this number the line says `no retries left`. |
| onCancel | () => void |  | Give up on the run. Shows Cancel run. |
| onRetry | () => void |  | Start the whole run over. Shows Run again, filled when there is no `onRetryFrom`, plain when there is. |
| onRetryFrom | () => void |  | Resume from the failed step and keep everything before it. Shows the filled Resume from this step button. |
| onSkip | () => void |  | Adds a Skip step button that continues with the next step. |
| retryIn | number |  | Seconds until the run retries itself. Shows a countdown row and calls `onRetry` once at zero. A new value restarts it. |
| retryLabel | string | "Run again" | Label of the retry button. Default `Run again`. |
| retryNote | React.ReactNode |  | Text after the countdown, for example "with batching (10 per call)". |

## Examples

### Error class: rate limit, timeout, permission, invalid output

### Actions: resume, run again, cancel

### Failure line: the step and the attempts

### Retry: a countdown, skip and extra actions

## In context

### Retry: until the attempts are gone

Resume from this step finishes the run, and Run again fails the step once more. At attempt 3 of 3 only Cancel run is left, and focus moves to the status line when the card goes.

### Report: copy the error ID and send it

The error ID is the last line of the detail, so the Code Block copies it with the rest. A Copy ID button and a mail link under the card copy or send only the ID, and a status line confirms the copy.

### Failed run: steps, error and spend

A run view after a failure: the state, the timeline with the failed step, the error with its actions, and what the run cost so far.

## For AI agents

`get_component("run-error")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
