API Reference
captureException
Manually report a caught error or arbitrary thrown value. Returns the event UUID, or null if dropped.
Signature#
typescript
function captureException(
error: unknown,
options?: CaptureOptions,
): string | null;
interface CaptureOptions {
severity?: 'low' | 'medium' | 'high' | 'critical';
isCrash?: boolean;
tags?: Record<string, string | number | boolean>;
componentStack?: string | null;
}Parameters#
| Name | Type | Default | Description |
|---|---|---|---|
| error* | unknown | — | Error instance, string, or arbitrary thrown value. Non-Error values are normalized into a synthetic Error so fingerprinting still works. |
| options.severity | enum | 'medium' | low | medium | high | critical. Crashes auto-promote to critical. |
| options.isCrash | boolean | — | Mark this error as a fatal crash. Crashes always have severity 'critical' and trigger replay flush. |
| options.tags | object | — | Per-call tags. Merged over scope tags (setTag/setTags), with per-call values winning on conflict. |
| options.componentStack | string | — | React component stack. Set automatically by ReliableErrorBoundary; rarely needed manually. |
Return value#
Returns the new event's UUID as a string. Returns null if the SDK isn't initialized, the error was de-duplicated within the 5s window, or beforeSend dropped the event.
typescript
const eventId = captureException(err);
if (eventId) {
showFeedbackDialog({ eventId });
} else {
// Either init() wasn't called yet, or this error was de-duped
}Examples#
typescript
// Basic — caught error
try {
await fetchUser();
} catch (err) {
captureException(err);
}
// With severity
captureException(err, { severity: 'high' });
// With tags for filtering in the dashboard
captureException(err, {
severity: 'high',
tags: {
flow: 'checkout',
payment_provider: 'stripe',
plan: 'pro',
},
});
// Non-Error thrown values are normalized
captureException('user double-clicked');
captureException({ code: 'EBADCSRF' });
captureException(42); // works, but please use a string
// Mark as crash for critical-severity classification
captureException(new Error('chunk load failed'), {
isCrash: true,
});Works without auto-capture#
captureException works whether or not captureErrors is enabled. The flag only gates the automatic window.error / unhandledrejection listeners — manual reporting is always available as long as init() has been called.
Tags vs. scope tags
Tags passed in
options.tags apply only to this event. To attach a tag to all future events from this session, use setTag() / setTags(). Per-call tags override scope tags on conflict.