Exceptions

The Exceptions page (sidebar Exceptions) lists errors your application reported to Beacon, grouped by fingerprint so repeated occurrences of the same underlying bug roll up into a single row. Pair it with stack traces, breadcrumbs, and the affected actor / version to investigate.

Prerequisites

Plan: Exception tracking is available on Trial, Pro, Business, and Enterprise. Starter accounts see an upgrade prompt instead of the Exceptions page.
Permission: view_exceptions.

How exceptions get into Beacon

Your application code calls the SDK’s ReportException (.NET / C++) or reportException (JavaScript) method when it catches an exception you want tracked. Beacon does NOT auto-capture every unhandled exception in your application — you choose what to report. This keeps the firehose noise-free and avoids accidentally shipping sensitive stack frames.

A reported exception must include:

Exception type — the class / kind name (e.g., System.IO.FileNotFoundException).
Severity — either fatal (the application can’t continue) or non_fatal (recovered).
Occurred-at timestamp.
The same actor_id, source_app, source_version that ride on regular events.

Optional, but strongly recommended:

Message — short human-readable detail (truncated to 1000 characters).
Stack trace — captured by the SDK from the exception object (truncated to 32,768 characters).
Breadcrumbs — a JSON array of recent application activity for context (free-form; see the SDK guide for the convention each SDK uses).
Session ID — links the exception to the user session in which it happened.
Environment context — OS / runtime / app metadata, typically populated automatically by the SDK.

Fingerprinting

Beacon computes a fingerprint for every exception from its type plus its stack trace. Two reports with the same type and a structurally similar stack trace get the same fingerprint and are grouped together on the list page. Without fingerprinting, every occurrence would be its own row and the list would be unmanageable.

A fingerprint stays the same across application versions as long as the stack frames at the failure site don’t change. A refactor that moves the failing function will produce a new fingerprint.

Read the list

Default time range is the last 30 days. Filters at the top of the page:

Source App — narrow to one product.
Source Version — narrow to one version.
Severity — fatal or non_fatal. Leave blank to see both.
Time range — custom or a preset.

Stats cards above the table summarise the entire filter window (not just the visible page) — total occurrences, unique fingerprints, fatal count, non-fatal count.

The table shows one row per fingerprint with these sortable columns: Exception Type, Occurrences, Affected Actors, Fatal / Non-Fatal, First Seen, Last Seen. New fingerprints carry a small “new” badge. Click a row to drill into details.

The list is keyset-paginated. The first 20 fingerprints load immediately; click Load more to fetch the next page. The stats cards stay correct as you load more — they always reflect the full window.

Drill into a fingerprint

Clicking a row navigates to /exceptions/[fingerprint] and shows:

Summary stats — total occurrences, distinct affected actors, time range first → last seen, severity breakdown.
Recent occurrences table — chronological list of individual occurrences. Each row expands to reveal:
- Message (if supplied)
- Session ID (shown as text — not a clickable link to Sessions today)
- Environment context (OS, runtime version, etc.)
- Stack trace (formatted, scroll-bar for long traces)
- Breadcrumbs (rendered as a chronological JSON array)

The list is the most recent occurrences for that fingerprint, capped per request.

Common questions

My exception isn’t grouping the way I expect. Two exceptions with the same type but different stack frames at the failure site fingerprint differently. That’s usually correct — they’re failing in different code paths. If you want them combined, refactor the call sites to share a common helper so the failure site is the same.

I sent a severity value that wasn’t accepted. The only valid values are fatal and non_fatal. Anything else returns a 422 at ingest.

Stack traces are missing. The SDK reads the stack trace from the exception object; if you constructed an Exception manually without a stack (or pre-formatted a string), the field is empty. Pass the original exception object to the SDK so it can read the stack at the point of throw.

Long stack traces are cut off. Beacon truncates at 32,768 characters. For deeper traces, simplify the exception by re-throwing at a higher boundary, or log the full trace to your own infrastructure separately.

Can I delete an exception? No. Exception reports are retained for the lifetime of your plan’s retention window and then purged automatically.

→ Segments