Run Error
ProThe 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
The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 2 of 3HTTPError: 429 Too Many Requests
at fetchInvoices (tools/invoices.ts:42)
at runStep (runtime/step.ts:118)
retry-after: 60
error id: err_8f3a21c9The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 2 of 3HTTPError: 429 Too Many Requests
at fetchInvoices (tools/invoices.ts:42)
at runStep (runtime/step.ts:118)
retry-after: 60
error id: err_8f3a21c9The invoice API is still limiting requests. Wait a minute, then start a new run.
fetch_invoices· Attempt 3 of 3 — no retries leftHTTPError: 429 Too Many Requests
at fetchInvoices (tools/invoices.ts:42)
at runStep (runtime/step.ts:118)
retry-after: 60
error id: err_8f3a21c9The invoice API is still limiting requests. Wait a minute, then start a new run.
fetch_invoices· Attempt 3 of 3 — no retries leftHTTPError: 429 Too Many Requests
at fetchInvoices (tools/invoices.ts:42)
at runStep (runtime/step.ts:118)
retry-after: 60
error id: err_8f3a21c9Installation
Run Error comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { RunError } from "@wunderui/react"Then use it:
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.
The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 2 of 3HTTPError: 429 Too Many Requests
at fetchInvoices (tools/invoices.ts:42)
at runStep (runtime/step.ts:118)
retry-after: 60
error id: err_8f3a21c9The CRM did not answer after three attempts. Check its status, then start a new run.
sync_contacts· Attempt 3 of 3 — no retries leftTimeoutError: no response after 30000 ms
at crmRequest (tools/crm.ts:77)
at runStep (runtime/step.ts:118)
error id: err_8f3a21c9The agent cannot send from this mailbox. Ask an admin for access, then start a new run.
send_reply· Attempt 1 of 1 — no retries leftPermissionError: 403 Forbidden
mailbox: info@wunderui.com
scope: mail.send
error id: err_8f3a21c9The reply could not be read as a deal update. Resume to ask for it again.
update_deal· Attempt 1 of 3ValidationError: "close_date" must be an ISO date
received: "next Tuesday"
at updateDeal (tools/deals.ts:31)
error id: err_8f3a21c9Actions
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.
The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 1 of 3The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 1 of 3The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 1 of 3The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 1 of 3Failure 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.
The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoices· Attempt 2 of 3The invoice API is limiting requests. Wait a minute, then resume.
fetch_invoicesThe invoice API is limiting requests. Wait a minute, then resume.
The invoice API is limiting requests. Wait a minute, then resume.
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.
429 Too Many Requests
Rate limit exceeded for this file. Retry-After: 38s.
send_code_connect_mappingsThe export timed out
export_pdfKeyboard 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.
- TaborShift+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 , 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.
The invoice API refused the request
fetch_invoices· Attempt 2 of 3HTTPError: 429 Too Many Requests
at fetchInvoices (tools/invoices.ts:42)
at runStep (runtime/step.ts:118)
retry-after: 60
error id: err_8f3a21c9- 1data-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.
- 2
A 16 px warning triangle in the red text colour.
- 3
The message in 14 px semibold red text. It says what happened and what to do.
- 4Optional
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.
- 5Optional
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| message required | ReactNode | — | The headline: what happened and what to do, in one or two sentences. Any node. |
| failedStep | ReactNode | — | The step that threw, such as . Shown after in monospace. |
| attempt | number | — | The attempt that just failed, counting from 1. Needs to be shown. |
| maxAttempts | number | — | How many attempts the step gets. At or above this number the line says . |
| 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 . |
| 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. |
| defaultOpen | boolean | false | Opens the error detail on the first render. It is only the starting state; the person can still close it. |
| description | ReactNode | — | Text under the message, for a human explanation of the failure. |
| retryIn | number | — | Seconds until the run retries itself. Shows a countdown row and calls once at zero. A new value restarts it. |
| retryNote | ReactNode | — | Text after the countdown, for example "with batching (10 per call)". |
| onSkip | () => void | — | Adds a Skip step button that continues with the next step. |
| retryLabel | string | "Run again" | Label of the retry button. Default . |
| cancelLabel | string | "Cancel run" | Label of the cancel button. Default . |
| actions | ReactNode | — | Extra actions appended to the row of buttons. |
| className | string | — | Extra classes for the card, for example . |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("run-error")The full library index for assistants is at /llms.txt.
Related components
- Done420 tok$0.01640ms
Input
status: overdue, age: 30+ daysOutput
14 invoices, $42,860 in total - Done3,420 tok$0.042.1s
Input
14 invoice idsOutput
14 contacts, all with an email address - Running2,310 tok
Input
template: invoice-overdue-30 - Pending
Input
to: 14 recipients - PendingLog the result
AI & Agents5 stylesProRun TimelineEvery step of a run in order, with duration, tokens and expandable input/output.- $
pnpm vitest run invoiceexit 03.8 sRUN v3.2.4 /srv/wunderui
✓ src/jobs/invoice-reminders.test.ts (6 tests) 412 ms
✓ src/jobs/reminder-template.test.ts (3 tests) 98 ms
Test Files 2 passed (2)
Tests 9 passed (9)
Duration 3.8 s
AI & Agents4 stylesProTerminal OutputThe result of a code-execution tool call: command, exit code, run time, stdout and stderr.