Skip to content
WunderUI

Run Error

Pro

The card for a run that stopped: what failed, at which step, how many attempts are left, and buttons to resume, run again or cancel.

Playground

Installation

Run Error comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • Terminal Output for a failed command with its exit code and output
  • Plan Step for one failed row in a plan, with a Retry button on the row
  • Alert for a failed tool call or any other short notice, with the way forward next to it
  • Run Timeline for every step of the run, including the one that failed

Error class

The card has no error classes. The message says what happened and what to do, and your handlers decide what can be pressed: a rate limit can be resumed, a missing permission cannot.

Actions

Each button appears only when its handler is passed. Resume from this step is the filled button when it is there; otherwise Run again is.

Failure line

The line under the message names the step that failed and counts the attempts. Both are optional; the attempts need the current and maximum number together.

Retry

retryIn counts down to an automatic retry and calls onRetry once at zero. onSkip adds Skip step, actions appends your own buttons, and description, retryLabel and cancelLabel adapt the texts.

Keyboard interactions

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.

TaborShiftTab
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 , so Tab skips it. Focus shows as an indigo border with a 2 px ring.
EnterorSpace
On the detail button, opens or closes the detail and flips . On an action, presses it.

Behavior and motion

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

The figure marks the card with the detail closed. The error detail has no number: it is the row above the buttons.

  • data-slot="run-error"

    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.

  • A 16 px warning triangle in the red text colour.

  • The message in 14 px semibold red text. It says what happened and what to do.

  • Optional

    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.

  • Optional

    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.

  • Optional

    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

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    Don't put a status code, a stack trace or the word Error alone in the message. Those belong in the detail.

  • Don’t

    Don't use it for a mistake in a form field. A field error belongs next to the field.

API reference

RunError is a plain component, not a wrapper of a primitive, so this table lists every prop.

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.

PropTypeDefaultDescription
message requiredReactNode—The headline: what happened and what to do, in one or two sentences. Any node.
failedStepReactNode—The step that threw, such as . Shown after in monospace.
attemptnumber—The attempt that just failed, counting from 1. Needs to be shown.
maxAttemptsnumber—How many attempts the step gets. At or above this number the line says .
detailstring—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.
detailLanguagestring"text"The language label of the Code Block. Default .
onRetryFrom() => void—Resume from the failed step and keep everything before it. Shows the filled Resume from this step button.
onRetry() => void—Start the whole run over. Shows Run again, filled when there is no , plain when there is.
onCancel() => void—Give up on the run. Shows Cancel run.
defaultOpenbooleanfalseOpens the error detail on the first render. It is only the starting state; the person can still close it.
descriptionReactNode—Text under the message, for a human explanation of the failure.
retryInnumber—Seconds until the run retries itself. Shows a countdown row and calls once at zero. A new value restarts it.
retryNoteReactNode—Text after the countdown, for example "with batching (10 per call)".
onSkip() => void—Adds a Skip step button that continues with the next step.
retryLabelstring"Run again"Label of the retry button. Default .
cancelLabelstring"Cancel run"Label of the cancel button. Default .
actionsReactNode—Extra actions appended to the row of buttons.
classNamestring—Extra classes for the card, for example .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("run-error")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.