Skip to content

Error tracking

The script can report the JavaScript errors your visitors run into, grouped so that each bug shows up as one row. This page covers how to turn it on, what gets captured, how errors are grouped, releases, and where to read them.

Enabling error tracking

Error tracking is a site option. Turn it on in Settings, from the Errors view, or with MCP's update_site:

{ "site": 42, "tracker": { "errors": true } }

The change reaches visitors within five minutes, with no change to your code.

What gets captured

  • Uncaught errors (the error event on window).
  • Unhandled promise rejections.
  • Errors you catch and report yourself with nl.error.
  • console.error calls, if you also turn on the console_errors option. Many libraries log through it.

To report an error you've caught, in an error boundary or a catch block:

try {
  await checkout(cart)
} catch (error) {
  nl.error(error, { step: 'payment' })
}

The second argument is a set of properties, the same as on a custom event. To call nl before the script has loaded, see Custom events.

Deduplication and limits

  • Each Error object is reported once, however it reaches the script: thrown, passed to nl.error, or logged.
  • Repeats are batched. The first occurrence of an error is sent right away, and any repeats in the next 60 seconds are sent together as one report with a count.
  • Each page load sends at most 30 error reports.
  • Some errors are ignored: errors whose top stack frame belongs to a browser extension, ResizeObserver loop notices, and Script error. (an error from a cross-origin script, which comes with no message or stack).

From your servers

The Events API accepts errors too: send an event of kind error with a type or message, and optionally a stack, release and count. They're grouped together with the errors from the browser.

Grouping

An error's group is its type plus its message, with the parts that vary taken out:

TypeError: Cannot read properties of undefined (reading 'map')
ChunkLoadError: Loading chunk <n> failed.
  • Runs of digits, UUIDs, hex strings of 8 or more characters, URLs and email addresses are replaced with placeholders. Error codes are kept, such as Minified React error #310, so different codes end up in different groups.
  • Chrome, Firefox and Safari word their TypeErrors differently. nanolytics rewrites them to one form, so the same bug is one group across browsers.
  • A rejection with a value that isn't an Error gets the type UnhandledRejection.
  • The stack isn't part of the group, so a deploy, a new bundle or a source map never moves an error into a different group.

The trade-off is that two unrelated places in your code that throw the same message end up in the same group. The group's call sites let you tell them apart.

The group is the error_group dimension, and it's readable as it is, so you and your agent can use it in queries and filters without looking anything up.

Releases

Add your release to the script tag, and every error records it:

<script defer src="https://app.nanolytics.dev/s/pk_….js" data-release="2026.11.16"></script>

A release can be up to 64 bytes. release is a dimension, so you can see which release an error first appeared in, and whether it stopped after the next one.

Viewing errors

In the dashboard

The Errors view lists your error groups with their events, visitors, trend, and when each was first and last seen, filtered by the dashboard's filters. A group first seen within the selected range is marked New.

Each group has its own page with a chart, call sites, pages, browsers and releases, and its latest occurrences with their stacks. If an occurrence happened on a recorded page load, it links to the session replay, which opens at the moment of the error.

In a query

The errors metric counts occurrences. To see what broke this week:

{
  "range": "7d",
  "metrics": ["errors", "visitors", "first", "last"],
  "breakdown": { "dimension": "error_group", "order": "errors" },
  "filters": { "not": { "dimension": "error_group", "op": "is", "value": [""] } }
}

To see what's new since a deploy, run the same query over all, ordered by first. To see one group's trend, pages or browsers, filter on its error_group. See Query API.

Error group details

GET https://api.nanolytics.dev/v1/sites/{site}/errors/{group} returns a group's call sites (the top stack frame on your own host for each occurrence, ranked by occurrences), its releases, and its 10 latest occurrences, each with its page, browser, release, original message and stack frames. Counts include human sessions only, and are taken from the latest 1,000 occurrences.

From your agent

Your agent lists error groups with query and looks at one in detail with error. See MCP server.