> ## Documentation Index
> Fetch the complete documentation index at: https://tinyanalytics.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript Error Tracking

> Capture JavaScript errors and group them by message with occurrence counts, affected sessions, and stack traces in the Errors report.

Error tracking records the JavaScript errors your visitors hit and groups them by message in the **Errors** report, so you can see which errors are most common, how many sessions they affect, and the exact stack trace behind each one. It's **off by default** — you turn it on with one attribute on your tracking script.

## How do I turn on error tracking?

Add `data-track-errors` to your tracking snippet. It's off by default because most sites want to opt in deliberately.

```html theme={null}
<script defer src="https://dash.tinyanalytics.io/script.js"
  data-site-id="YOUR_SITE_ID"
  data-track-errors></script>
```

Once enabled, tinyanalytics automatically captures **uncaught exceptions** (`window.onerror`) and **unhandled promise rejections** — the two ways errors normally escape your code — and sends each as an `error` event.

## What does tinyanalytics record for each error?

Each captured error records the fields you need to reproduce it, all trimmed to safe limits:

| Field        | What it holds                                                                           |
| ------------ | --------------------------------------------------------------------------------------- |
| **Type**     | The error's name — `TypeError`, `ReferenceError`, and so on — used as the grouping key. |
| **Message**  | The error message, up to 500 characters.                                                |
| **Stack**    | The stack trace, up to 2,000 characters.                                                |
| **Location** | The `fileName`, `lineNumber`, and `columnNumber` where available.                       |

Errors are captured with the same page context as any other event — the page, browser, OS, device, and country — so you can see *where* and *for whom* each error happens.

<Note>
  tinyanalytics filters out noise automatically. Benign `ResizeObserver` loop warnings are dropped, and errors from cross-origin third-party scripts are ignored — only errors from your own site are recorded. Identical errors from the same visitor are de-duplicated within a 60-second window, so one broken loop doesn't flood your report.
</Note>

## How do I track an error manually?

To record an error you've caught yourself — in a `try/catch`, an error boundary, or a rejected request — call `trackError`:

```js theme={null}
try {
  await checkout()
} catch (err) {
  window.tinyanalytics.trackError(err, { step: 'payment' })
}
```

The second argument is optional metadata: any extra properties you want stored alongside the error, the same way [custom event](/docs/custom-event-tracking) properties work. Manual tracking works whenever the script is loaded, and pairs well with automatic capture for the errors your code already handles gracefully.

## How do I read the Errors report?

The Errors report lists one row per **distinct error message**, most frequent first. For each error you see:

| Column          | What it means                                                     |
| --------------- | ----------------------------------------------------------------- |
| **Error**       | The error type and message.                                       |
| **Trend**       | A sparkline of how often the error occurred over your date range. |
| **Occurrences** | The total number of times the error fired.                        |
| **Sessions**    | The number of distinct sessions that hit it — your blast radius.  |

**Click an error to open its details** and read every individual occurrence: the exact time, the visitor's page, browser, OS, device, and country, the person (linked to their [user profile](/docs/user-analytics)), the full message, and the stack trace with a clickable `file:line:column` reference.

The report honors your dashboard's [date range](/docs/web-analytics-dashboard), [filters](/docs/analytics-filters), and [segments](/docs/saved-analytics-segments) — so you can narrow to errors on one page, one browser, or one release.

## Common workflows

* **Triage by impact.** Sort by sessions, not occurrences, to fix the errors hurting the most people first.
* **Confirm a fix.** Watch an error's trend sparkline drop to zero after you deploy.
* **Scope a regression.** Filter to a browser or country to see whether an error is universal or environment-specific.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why aren't my JavaScript errors showing up in tinyanalytics?">
    Error tracking is off by default. Add the `data-track-errors` attribute to your tracking snippet and re-deploy, and tinyanalytics starts capturing uncaught exceptions and unhandled promise rejections as `error` events.
  </Accordion>

  <Accordion title="What's the difference between automatic and manual error tracking?">
    Automatic capture records the errors that escape your code — uncaught exceptions (`window.onerror`) and unhandled promise rejections — once `data-track-errors` is on. Manual tracking with `window.tinyanalytics.trackError(err, { ... })` records errors you already catch yourself in a `try/catch` or error boundary, with optional metadata. Use both together.
  </Accordion>

  <Accordion title="Does tinyanalytics capture errors from third-party scripts?">
    No. Errors from cross-origin third-party scripts are ignored, so only errors from your own site are recorded. tinyanalytics also drops benign `ResizeObserver` loop warnings, and de-duplicates identical errors from the same visitor within a 60-second window.
  </Accordion>

  <Accordion title="How do I tell how many people an error affects?">
    Read the **Sessions** column in the tinyanalytics Errors report — it counts the distinct sessions that hit the error, which is your blast radius. Sort by sessions rather than occurrences to fix the errors hurting the most people first.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Configure the tracking script" icon="sliders" href="/docs/configure-tinyanalytics-tracking-script">
    The `data-track-errors` attribute and every other option.
  </Card>

  <Card title="Track custom events" icon="hand-pointer" href="/docs/custom-event-tracking">
    Send named events and properties yourself.
  </Card>

  <Card title="Performance" icon="gauge-high" href="/docs/core-web-vitals-analytics">
    Core Web Vitals — the other health signal.
  </Card>

  <Card title="Tracking API" icon="paper-plane" href="/docs/api-reference/track-events-api">
    The `error` event type on the ingestion endpoint.
  </Card>
</Columns>


## Related topics

- [Configure the tinyanalytics Tracking Script](/docs/configure-tinyanalytics-tracking-script.md)
- [Custom Event Tracking](/docs/custom-event-tracking.md)
- [Connect an AI Agent with the MCP Server](/docs/api-reference/mcp-server.md)