Error tracking

The problem: errors you never see

A team ships a new checkout page on a Tuesday afternoon. Every test passes. The page works on every laptop in the office.

On Thursday, the support inbox has 40 tickets that all say the same thing: "the Pay button does nothing". Revenue from iPhones is down 30 percent since Tuesday.

The cause is one line. The new code calls Array.prototype.findLast, which an older Safari version on some phones does not have.

On those phones the click handler throws a TypeError and stops. The user sees nothing: no message, no spinner, just a button that does nothing. Nobody on the team could see it either, because the error happened in the user's browser, not on a server.

That is the core problem. Backend errors land in server logs you own. Frontend errors happen on millions of devices you don't own, in browsers, versions, extensions, and networks you never tested. Without a way to collect them, the first sign of a broken release is an angry customer, often days late.

What an error tracker does

An error tracker is a small script in your page plus a service behind it. Sentry, Bugsnag, Rollbar, Datadog RUM, and New Relic Browser are well-known products; some large companies build their own. They all do the same five jobs, and the rest of this lesson takes them one at a time. Between enrich and symbolicate, the SDK also scrubs and sends each event, which the frontend logging lesson covers.

1. Capture. Hook into the browser so that every uncaught error and every rejected promise nobody handled is noticed, plus the errors your framework catches for you.
2. Enrich. Attach what you need to debug: the stack trace, the release version, the browser, the page URL, and a short trail of what the user did just before (the breadcrumbs).
3. Symbolicate. Turn a stack trace that points at app.3f9c.js:1:48211 back into Checkout.tsx:88 using source maps, without publishing your source to the world.
4. Group. Fold 50,000 reports of the same bug into one issue with a count, so a human can read the list. This step decides whether the tool is useful or noise.
5. Alert. Tell the right person when something new appears, when a fixed bug comes back, or when a release makes the error rate jump.

With a tracker in place, the Tuesday story changes. Within minutes of the release, a new issue appears: a TypeError saying findLast is not a function, thrown in lastPaidItem. It has 1,200 events from 900 users, all on older Safari, first seen in release checkout@2.14.0.

An alert goes to the checkout team's channel. They ship a fix the same afternoon, and the 40 support tickets never happen.

Error tracking, logging, and RUM

Three tools collect data from the browser, and people mix them up. The [frontend logging lesson](/system-design/concepts/frontend-logging) covers how any event gets from the browser to a server: batching, sendBeacon, sampling, scrubbing personal data. We won't repeat that here. This lesson is about what is special about errors: catching them, decoding them, grouping them, and acting on them.

Capturing errors in the browser

Before you can group or alert on an error, something has to notice it. The browser gives you a few global hooks, and your framework gives you a few more. Each one sees a different slice of the failures, so a tracker installs all of them. Knowing which hook sees what is the most common interview follow-up on this topic.

window.onerror: uncaught exceptions

When JavaScript throws and nothing catches it, the browser fires an error event on window. The oldest way to listen is to assign window.onerror. It is called with five arguments: the message, the script URL, the line, the column, and the Error object itself. The fifth argument is the important one, because it carries the stack trace.

window.addEventListener("error", (event) => {
  if (event instanceof ErrorEvent) {
    // A script threw and nobody caught it.
    report({ kind: "exception", error: event.error, message: event.message,
             file: event.filename, line: event.lineno, col: event.colno });
  } else {
    // A resource failed: img, script, link. No message, no stack.
    const el = event.target;
    report({ kind: "resource", tag: el.tagName, url: el.src || el.href });
  }
}, true); // capture phase: resource errors do not bubble

window.addEventListener("unhandledrejection", (event) => {
  report({ kind: "rejection", error: event.reason });
});

window.onerror and addEventListener("error", ...) see the same script errors. The difference is resource errors.

When an img, script, or link fails to load, the browser fires a plain error event on that element, and it does not bubble up to window. Only a listener in the capture phase (the third argument true) sees it on its way down. window.onerror never does.

A failed resource tells you less than a script error: there is no message and no stack, only the element and its URL. That is still worth knowing.

Take a code-split chunk that fails to load after a deploy because the old file was deleted. If the bundler loads chunks through script tags, as webpack does, the failure shows up here, just before webpack's ChunkLoadError. A native import() that fails only rejects its promise.

unhandledrejection: promises nobody handled

Most modern code is asynchronous. An error thrown inside an async function does not reach window.onerror: it rejects the promise instead. If no .catch() or try/await handles that rejection by the end of the current task, the browser fires unhandledrejection on window. Its reason property holds whatever was rejected.

Two traps hide here. First, reason is not always an Error. Code can reject with a string, a number, an API response object, or undefined, and then there is no stack at all. Good trackers record the type and a short preview of the value, and teams add a lint rule that only Error objects may be thrown or rejected.

Second, a rejection can be handled late: the browser then fires rejectionhandled, and a careful tracker can drop the earlier report.

Framework hooks and error boundaries

UI frameworks catch errors during rendering so one broken component doesn't take down the whole page in a confusing way. Once a framework catches an error, the global hooks may never see it. So every framework has its own hook, and a tracker plugs into it.

• React has error boundaries: a class component with static getDerivedStateFromError (to show a fallback UI) and componentDidCatch(error, info) (to report it, with info.componentStack naming the components above the one that broke). React 19 adds two root options on createRoot and hydrateRoot: onCaughtError for errors a boundary caught and onUncaughtError for errors no boundary caught. They sit next to onRecoverableError (from React 18), for errors React recovered from by itself, such as a hydration mismatch. By default, React 19 passes uncaught errors to window.reportError, so the global error listeners see them too, and logs caught ones with console.error.
• Vue calls app.config.errorHandler(err, instance, info) for errors in components, watchers, and lifecycle hooks.
• Angular routes errors to its ErrorHandler class; you provide your own subclass that reports and then logs.
• Next.js turns an error.js file in a route folder into an error boundary for that route, and global-error.js into one for the root layout. SvelteKit has a handleError hook in hooks.client.js.

Error boundaries are easy to over-trust. A boundary only catches errors thrown while React renders: in render functions, lifecycle methods, and constructors of components below it. It does not catch errors in event handlers, in setTimeout callbacks, in promises, in server rendering, or inside the boundary itself. A click handler that throws goes straight to window.onerror, boundary or not.

Where you place boundaries is a product decision. One boundary at the root turns any render error into a blank page with an apology. Boundaries around each independent widget (the sidebar, the comments, the chart) let the rest of the page keep working while one panel shows "This part failed to load. Retry".

Every boundary should report what it caught, otherwise you have hidden the error from users and from yourself.

What all the hooks miss

• Errors before the tracker loads. If the SDK is the last script on the page, a crash during startup is lost. Load it first, or inline a tiny stub that queues errors until the SDK arrives.
• Web workers. A worker has its own global scope. An error inside it fires error on the worker's self and then on the Worker object in the page, not on window. Install a handler in the worker or listen on the Worker object.
• Silent failures. A button that does nothing because a condition is wrong, or a blank list because the API returned [], throws nothing at all. Error tracking can't see logic bugs; product metrics and logs have to.
• Browser crashes and freezes. If the tab runs out of memory or hangs, no JavaScript runs to report it. In Chromium browsers, the Reporting API covers part of this gap: after a crash, the browser itself sends a crash report with a reason such as oom (out of memory) to an endpoint you name in the Reporting-Endpoints header. A heartbeat in a worker can detect a frozen main thread.

Try it: pick a failure below and see which hooks notice it. The pattern to remember is that each hook covers a different kind of failure, and only the set of all of them gives good coverage.

Getting a stack trace you can read

Capturing an error is half the job. The report also has to say where in your code it happened. Two things get in the way: the browser hides details of errors from other origins, and your shipped code is minified beyond recognition.

"Script error." and cross-origin scripts

Many sites serve their JavaScript from a CDN on another origin, such as cdn.shop.com for a page on www.shop.com. When a script from another origin throws, the browser protects that origin by default: your handler gets the message "Script error.", an empty file name, line 0, column 0, and error set to null. Without this rule, any page could load your script and read secrets out of its error messages.

The fix has two halves, and both are required. The script tag asks for a CORS request with crossorigin="anonymous", and the CDN answers with Access-Control-Allow-Origin: https://www.shop.com (or *).

Then the browser treats the script like your own and passes the full error through. Module scripts (type="module") are always fetched with CORS, so they need the header in any case. The [CORS lesson](/system-design/concepts/cors) explains the headers.

Third-party scripts you don't control (ads, chat widgets, tag managers) often can't send the header. Their errors stay as "Script error.". Most teams filter them out entirely, since they can't fix them anyway; chapter 7 comes back to this.

Minified stacks are useless on their own

Production bundles are minified: whitespace removed, names shortened to one letter, many files joined into one. The whole bundle is often a single line. In Chrome, a stack frame from it looks like at n (https://cdn.shop.com/assets/app.3f9c1a.js:1:48211); Firefox and Safari write n@ and the URL instead. The function is called n, the line is 1, and the only useful number is the column.

A source map is a JSON file the bundler writes next to each bundle. It lists the original files (sources), the original names (names), optionally the original code itself (sourcesContent), and a compact mappings string. For each mapped position in the minified file, mappings says which file, line, column, and name it came from. Turning a minified frame back into an original one is called symbolication.

The format was a de facto standard for over a decade. Since December 2024 it is an official standard, ECMA-426, maintained by a TC39 task group.

Minified (what an older Safari reports)
  TypeError: e.findLast is not a function
    n@https://cdn.shop.com/assets/app.3f9c1a.js:1:48211
    r@https://cdn.shop.com/assets/app.3f9c1a.js:1:51907

Symbolicated (what the tracker shows; the message is not rewritten)
  TypeError: e.findLast is not a function
    at lastPaidItem (src/checkout/totals.ts:41:22)
    at onPayClick (src/checkout/PayButton.tsx:88:9)

Hidden source maps and debug IDs

Normally a bundle ends with a comment such as //# sourceMappingURL=app.3f9c1a.js.map, and anyone with DevTools open can download the map and read your original code. Many companies don't want that. The common answer is a hidden source map: the bundler still writes the .map file but leaves out the comment (devtool: "hidden-source-map" in webpack, build.sourcemap: "hidden" in Vite). The build uploads the maps to the error tracker and does not deploy them to the CDN.

The tracker then has to find the right map for each error. The old way matches on the release name plus the file URL, which breaks when the CDN path changes or a file is served from two URLs.

The newer way is a debug ID: the build tool writes the same unique ID into the bundle and its map, and a tiny snippet in the bundle exposes it at runtime. The SDK sends the ID with each error, and the tracker looks up the map by ID, with no URL guessing.

Debug IDs for JavaScript started in Sentry's build tooling. A proposal to add a debugId field to ECMA-426 is in progress at TC39, so for now the exact format depends on your tracker's build plugin.

Breadcrumbs and context: what happened before

A stack trace tells you where the code broke. It rarely tells you why. Cannot read properties of undefined (reading 'price') at totals.ts:41 is clear about the line, but the real question is how the cart got into a state with an item that has no price. For that you need the story leading up to the error.

Breadcrumbs

Breadcrumbs are small events the SDK records all the time, in memory, and attaches to an error report only when an error happens. Most are collected automatically by wrapping browser APIs:

• Navigation: route changes from history.pushState and the popstate event, with the from and to paths.
• Clicks and key presses: a short description of the target, such as button#pay-now or button[aria-label="Remove item"]. Not the text the user typed.
• Network: each fetch and XMLHttpRequest with method, URL, status, and duration, such as POST /api/cart/apply-coupon 422 180ms.
• Console: console.warn and console.error calls, which often hold the clue.
• Your own: calls like addBreadcrumb({ category: "cart", message: "coupon applied" }) at important steps.

They live in a ring buffer: a fixed-size list (often the last 50 to 100 entries) where each new entry pushes out the oldest. Memory stays flat no matter how long the tab is open, and nothing is sent until an error happens. That makes breadcrumbs nearly free.

Start at the error at the bottom and read upward. In the example, the user applied a coupon, the server answered 422, the app logged a warning, and then the totals code crashed reading price. The bug is not in totals.ts at all: the coupon error path leaves a half-built item in the cart. The stack alone would have sent you to the wrong file.

Context: tags that make errors searchable

Every report also carries context: fields that let you filter and compare. Some come for free, some you set once at startup or login.

Feature flags deserve special attention. If the new pricing code ships behind a flag at 10 percent, the release number alone won't explain why only some users crash. Tagging every report with the active flags lets you see "100 percent of these errors have newPricing: on" and turn the flag off in seconds. The [feature flags lesson](/system-design/concepts/feature-flags) covers flags themselves.

Grouping: from 50,000 events to 12 issues

A busy app sends thousands of error events an hour. Nobody can read them one by one. The tracker folds events that come from the same bug into one issue, with a count, a first-seen time, a last-seen time, and the number of users affected. Grouping is the step that decides whether the tool is useful: group too little and one bug floods the list, group too much and a new bug hides inside an old one.

Fingerprints

Each event gets a fingerprint: a short hash computed from the parts of the event that identify the bug. Events with the same fingerprint join the same issue. The whole art is choosing which parts go into the hash and how to clean them first.

1. Symbolicate the stack, so frames name real functions and files instead of n in app.3f9c1a.js. Without this, every deploy changes the bundle name and every bug becomes a new issue.
2. Keep only your own frames ("in-app" frames). Frames inside React, the bundler runtime, or a vendor library are the same for thousands of different bugs.
3. Drop line and column numbers, or at least don't rely on them alone. Adding one line above a function moves every frame below it, and the same bug would become a new issue after an unrelated edit.
4. Hash the error type plus the function and file names of those frames. If there is no usable stack, fall back to the type plus a normalized message: the message with numbers, IDs, URLs, and quoted values replaced by placeholders.

Why the same bug looks different in each browser

Grouping by message sounds simple, but browsers word the same error differently and format stacks differently. The same line of code, item.price with item undefined, produces three different reports:

So a tracker parses each format into the same structure (function, file, line, column) and groups on the frames, not the text. After symbolication, all three point at cartTotal in totals.ts, and they land in one issue. The wording in the table is from recent versions; engines reword messages from time to time, which is another reason not to group on them.

When the default is wrong

Stack-based grouping fails in a predictable case: shared helpers. If every API call goes through fetchJson, and fetchJson throws on any non-2xx status, then a 500 from the orders API and a 422 from the coupon API have the same stack. They merge into one issue, and fixing one looks like it didn't help. The fix is a custom fingerprint for those errors, such as ["api", "POST /api/cart/apply-coupon", "422"]: the route pattern and the status.

The opposite failure is a message with an ID in it, like Loading chunk 7412 failed. If the tracker groups on message, every chunk number is a new issue. Normalizing numbers away, or a custom fingerprint ["chunk-load-failed"], folds them together.

The lab below plays a stream of 59 events from two releases through four grouping rules. Watch two things: how many issues you get, and whether the new bug in release 2.14 (a findLast call that breaks older Safari) shows up as its own new issue.

Releases, regressions, and user impact

Most new errors arrive with a deploy. So the most useful question a tracker answers is not "what is broken?" but "what did this release break?". That needs every event tagged with the release that produced it, and a few numbers that compare releases fairly.

Release tracking

The build picks a release name, often the app name plus a version or the git commit (checkout@2.14.0 or web@8f3c2d1). The same string goes to three places: into the bundle so the SDK sends it with every event, onto the uploaded source maps, and to the tracker as a deploy marker with the list of commits. With those three, the tracker can say "first seen in 2.14.0" and even point at the commit that last touched the file in the top frame (a suspect commit).

Remember that releases overlap. A single-page app keeps running the old bundle in tabs that were opened before the deploy, sometimes for days. For a while, events arrive from two or three releases at once. Every chart that compares releases has to split by release, not by time.

The life of an issue

Each issue has a state that a human or the tracker changes. The states matter because alerts hang off the transitions: you want to hear about an issue when it is new and when it comes back, not every time it fires.

The key state is resolved in a release. If you mark an issue resolved in 2.14.0, the tracker ignores later events from 2.13.x (old tabs still hit the old bug) and only treats events from 2.14.0 or newer as a regression. Without that rule, every fixed bug "regresses" for days after the fix, and people learn to ignore regression alerts.

Measuring user impact

Event counts mislead. One user stuck in a loop that retries every second can send 10,000 events in three hours, while a crash on the Pay button that hits 2,000 people once each sends 2,000. Rank issues by users affected first, and weigh by where it happens: an error on checkout matters more than one on the settings page.

To judge a whole release, trackers use session-based numbers. A session is one visit to the app. Each tracker defines where a session starts and ends, for example a new one after a period without activity.

• Crash-free sessions: the share of sessions with no unhandled error. If release 2.13 had 200,000 sessions and 1,200 had an unhandled error, it is 99.4 percent crash-free.
• Crash-free users: the same, counted per user over a day or a week. It is lower than the session number, because a user with five sessions has five chances to crash.
• Errors per session: total error events divided by sessions. Good for spotting a release that throws more handled errors without crashing.

In the chart, 2.14.0 drops from 99.4 to 97.8 percent crash-free in its first hour. That is about 1 in 45 sessions failing, almost four times worse than the release before. This is the signal to roll back or turn off a flag, before reading a single stack trace. Compare a new release in its first hours against the old one over the same hours, not against a week of history: early adopters are a different mix of devices.

Noise, filtering, and alerting

Turn on an error tracker for a large site and the first day is humbling: hundreds of issues, most of them not your bugs. If you alert on all of them, people mute the channel within a week, and then the real regression goes unseen. Cutting noise comes before alerting.

Where the noise comes from

Filter in two places. In the SDK, an allow list of your own script URLs and a short list of ignored messages stop junk before it costs the user any bandwidth. On the server, inbound filters catch what the SDK missed, and you can change them without a deploy. Keep the client list short: every rule there ships in the bundle and only changes with a release.

Volume needs limits too. A bug inside a requestAnimationFrame loop can throw 60 times a second per user. Good SDKs send the same error at most a few times per page, and trackers apply spike protection and per-project quotas so one bad release doesn't use up the month's budget in an hour.

Alert rules that people trust

An alert is worth sending only if someone should act now. Four kinds cover most needs:

• New issue with real reach: first seen in production and affecting at least 10 users within an hour. The user minimum filters out one-off weirdness from a single odd device.
• Regression: a resolved issue has events from a release that should contain the fix.
• Spike: an issue's rate in the last 15 minutes is several times its usual rate at this hour, and above a minimum count. Comparing with the same hour last week handles the normal daily traffic curve.
• Release health: crash-free sessions for the newest release fall below a line, such as 99 percent, once it has enough sessions to judge.

Fixed thresholds are the trap. "Alert when an issue has more than 500 events an hour" fires every evening at peak traffic and stays quiet at 3 a.m., when a real outage only produces about 200. Relative rules with a floor, like "3 times the usual rate and at least 50 events", follow the traffic curve. Try both in the simulator below.

Then route alerts to owners. Map file paths or routes to teams (src/checkout/** goes to the payments team), the way a CODEOWNERS file maps code to reviewers. Page a person at night only for release health and checkout-level crashes; send the rest to the team's channel or a daily digest.

Privacy, performance, and cost

An error tracker sends data from users' devices to a third party, runs code on every page, and bills per event. Each of those needs a deliberate choice. The [frontend logging lesson](/system-design/concepts/frontend-logging) covers the general rules for scrubbing and sending; here are the parts that are special to errors.

Errors leak personal data

Error reports pick up personal data in places people don't expect. A validation error says Invalid email: jane@example.com. A password reset page throws with ?token=9f2c... in the URL.

A breadcrumb records GET /api/users/jane@example.com. Session replay sees everything on screen.

• Scrub in the browser with the SDK's hooks (Sentry calls them beforeSend and beforeBreadcrumb): strip query strings, replace emails and long digit runs, drop request and response bodies.
• Scrub again on the server with pattern rules, as a safety net for what the client missed, including events from old releases.
• Identify users with an opaque ID, not an email or name. Support can still look a user up in your own systems.
• Limit storage: turn off IP address storage if you don't need it, pick the tracker's region that matches your users (such as an EU region for EU data), and keep events for 30 to 90 days, not forever.

Keeping the SDK light

A full-featured SDK with tracing and replay can add tens of KB of compressed JavaScript, which competes with your own code on a slow phone. But loading it late means missing errors during startup, which are often the worst ones. The usual answer is a split:

Getting events through, and paying for them

Ad blockers block many tracker domains, which hides a share of your errors, and a bigger share on sites with tech-savvy users. A common fix is a tunnel: the SDK posts to a path on your own domain, such as /monitoring, and your server forwards the event to the tracker. Your server should check the event points at your project, so the tunnel can't be used to send arbitrary data.

Trackers bill per event, so cost follows volume. Random sampling of errors is a poor way to save money: it hides rare bugs, the ones you most need to see. Better levers are the ones from the noise chapter: filter junk at the source, send each repeated error once per page with a count, and set quotas per project. Sample performance traces and replays heavily; keep errors at 100 percent if you can.

Using it in a system design interview

Error tracking rarely is the question. It is part of a good answer to almost any app question (a checkout, a document editor, a dashboard) in the last ten minutes, when the interviewer asks "how would you know it works in production?" or "what happens when this fails?". A short, concrete answer there is a strong senior signal.

What to say and draw

1. Capture: global error (capture phase) and unhandledrejection listeners, error boundaries around independent parts of the UI that report what they catch, and manual reports in catch blocks for unexpected failures.
2. Readable stacks: crossorigin plus CORS on the CDN, hidden source maps uploaded from CI with a debug ID or release.
3. Context: release, route pattern, browser, opaque user ID, active feature flags, and a breadcrumb trail.
4. Grouping and alerting: fingerprints on in-app frames, new-issue and regression alerts with user minimums, crash-free sessions per release gating the rollout.
5. Privacy and cost: scrubbing in beforeSend and on the server, filtering noise at the source, keeping errors unsampled.

On the whiteboard, a small box in the browser labelled "error SDK" with an arrow to an "error tracker" box is enough, plus a line from CI to the tracker for source maps. Draw the CI line: it shows you know symbolication is a build-time job.

How deep to go by level