Skip to content

Components · Reference

Error Component

A shared TanStack Router error page with localized messages, hard refresh, home navigation, and copyable error details.

Last updated October 26, 2026

Overview

ErrorComponent is a domain-neutral TanStack Router error page for standard and Effect errors. Domain code owns error classification and localized messages. English and French defaults are selected from the explicit locale prop. The optional messages map adds or overrides labels by locale, including additional languages.

Set the active locale once with KrakstackProvider; pass locale directly only when a component needs an override. Message overrides are keyed by arbitrary locale strings, so additional languages can be supplied with messages={{ es: { ... } }}. Exact locale keys such as es-MX take precedence over base keys such as es; English is the final fallback.

Install

shell
bunx shadcn@latest add @krak-stack/error-component

Setup

tsx
import { ErrorComponent } from "@/components/ui/error-component";

const router = createRouter({ routeTree, defaultErrorComponent: ErrorComponent });
export const Route = createRootRoute({ errorComponent: ErrorComponent });

Retry calls window.location.reload() for a full document refresh. Home navigation uses TanStack Router's / link, including locale rewrites. Set retryable={false} to hide retry. Blank messages use the localized fallback description.

Copy Error Details

The copy action includes the error name, displayed message, page pathname, capture timestamp, and locale. Clipboard failures reveal selectable text. Raw causes, request headers, URL query strings, fragments, and stack traces are not appended. Error messages are application-owned text and should be suitable for sharing.

For Effect HTTP errors, Reference is automatically extracted from the failed request's existing trace headers using HttpTraceContext.fromHeaders. W3C traceparent, compact b3, and multi-header B3 are supported. Wrapped errors are followed through their standard cause chain, with cycle protection. Missing or invalid trace IDs are omitted. The component never generates a new ID.

Optional diagnostics fields add app name and release version. An explicit reference overrides automatic trace extraction:

tsx
<ErrorComponent {...props} diagnostics={{ app: "Kokobi", version: releaseVersion }} />

Users can paste the report into their support channel and the reference can be searched in tracing tools.

Effect Boundaries

Map transport failures to meaningful localized domain errors while preserving the original error in cause. This retains the HTTP request and its automatically propagated trace ID. At promise-based router boundaries, use Effect.runPromiseExit and throw Cause.squash(exit.cause) on failure. No custom display-error class is required. Errors that discard the original HTTP error cannot supply its trace ID automatically.

The package exports ErrorComponent, ErrorComponentProps, and ErrorComponentMessages from @krak-stack/registry/error-component.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Registry Dependencies

Preview

Error Component
Copy a sample error report or try a full page refresh. The home link returns to the site homepage.

Unable to load this page

We couldn't load this example. Try refreshing the page, or copy the error details to share with support.
Go to homepage