Client Error Insights

Browser error insights need three features, all on by default:

The collector is registered only when all three are on. With any of them off, browser errors are still counted by vaadin.client.errors — nothing describes them.

The insights are served at /actuator/vaadin/observability, alongside the interaction and data query insights. Expose the endpoint as described in Exposing the Endpoint:

Every report carries a kind naming the browser event that raised it. It’s both the kind tag on the vaadin.client.errors counter and the kind field on the insight, and it holds one of three values:

Two more fields are published whatever the detail settings say:

source and frame are dropped when the browser supplied nothing that is actually a location: a cross-origin script reports Script error. with no filename, and a rejection has no filename at all.

Both source and frame are locations only — see What Reaches Source and Frame. The function name that stood in front of the frame is not part of it and travels separately, under the same gate as the message; see Sensitive Detail.

Reports are grouped by route, kind, source, and frame, so the same script failing in a hundred tabs is one insight with a hundred occurrences. The route is a template, so orders/17 and orders/18 group under one orders/:orderId insight rather than one per parameter value.

A client error appears in the shared insights array with type: "client-error":

The summary, the replay steps, and the suggestion all identify the error by its frame, falling back to source when the stack held no usable frame, and to the phrase "an unreported script" when the browser named no location at all.

Note what measures says about the timestamps: firstSeen and lastSeen are arrival times, not the moments the errors happened. An arrival can lag the error by a whole outage — see Reports That Waited Out an Outage.

Unlike an interaction insight, a client error carries no applicationFrame: there is no server-side stack, so the location in frame is the only place to look. The suggestion says so explicitly, which matters when the payload is handed to an AI agent — the code to open is a client-side view, a web component, or a bundled dependency, not a Java class.

Each insight carries up to three of its most recent occurrences in examples, keyed by at rather than timestamp. An example reports its own bufferedMs, the sessionId (a short one-way hash by default), and the uiId of the tab that reported it. It also carries a message when detail collection is on and the browser supplied one.

source and frame are published regardless of the detail setting, so the kit keeps them only when they’re locations. Both are checked twice: in the browser, to keep the buffer and the request small, and again on the server — which is the check that counts, because any script on the page can call the collector’s endpoint directly.

A location is a file:line or file:line:col whose file has an extension or a path separator, contains no whitespace of any kind, and is built only from the characters a path or URL is made of. The line and column are at most eight digits each: a position in a file, not a number somebody wanted published. The file itself isn’t capped that way, because a bundle really can be called chunk-1234567890123.js.

Several kinds of text are refused outright:

An @ is treated as part of the path when the text before it is rooted or schemed, so /node_modules/@vaadin/router/router.js, https://unpkg.com/lit@3.1.0/index.js, and a dev server’s /@fs/ paths all survive whole, version pins included. An @ after anything else is a function name glued to a location, so it’s read as an engine’s name@location separator and taken apart, with the path going to frame and the name to function.

A stack line is split on the separator its engine uses, and only the location half is validated and kept. V8’s form is delimited by the engine — an at prefix, or the location wrapped in parentheses — so the split point isn’t in doubt. The @ form of SpiderMonkey and JavaScriptCore has no delimiter, so before its @ counts as a separator the whole line must look like a frame line: no whitespace anywhere, and both a line and a column. Without that rule, any sentence containing an @ would split into a "name" and something that passes for a location.

The message-line rejections are the ones worth knowing about, and not because of what they’d add. V8 opens a stack with the error’s message, a message can span lines, and the first line that parses wins — so new Error('Upload failed for:\n' + url) wouldn’t merely contribute a host, it would take the place of the frame that actually threw.

The cost of the @-form rule is that Safari writes frames named global code, module code, and eval code, and Firefox writes space-containing async markers such as promise callback*loadData. These contain spaces, so they’re no longer read as frames; the search moves to the next line, and where such a line is the only one in the stack the insight falls back to source, which the browser supplies for a top-level script error.

A browser that has lost the server can’t report anything, which is exactly when scripts tend to fail. The collector holds its buffer in sessionStorage and flushes it when the connection returns, so an error raised during an outage still arrives.

bufferedMs is how long a report waited for its browser to reach the server again. It counts only time the browser spent unreachable, never the wait for the next flush, so a routine error reports zero however long it sat in the buffer.

Read a non-zero value as "this couldn’t be delivered when it was raised" rather than "this happened during an outage". A report taken while the browser was still connected accrues the outage that starts before the next flush, so the two aren’t the same claim.

maxBufferedMs on the insight is the largest value in the group, so it speaks for at least one occurrence and not necessarily the most recent one. The bufferedMs of each example says which ones waited.

A report that survives a reload keeps the wait it had accrued — it’s written to sessionStorage alongside the report — but the clock it would have gone on accruing against is gone with the page, so a tab that reloads mid-outage resumes counting from the load.

The insights payload is meant to travel — into an issue tracker, an AI agent, a chat message — so a browser error’s message and function name are withheld unless you ask for them. The message because it can quote anything the page was working with, and the name for the same reason: a page can set any function’s name to any string, and the browser prints whatever it’s told, so a name is text the page chose rather than a fact about the code.

Turn both on when you need them:

The message is then present as message (truncated to 200 characters) on the insight and on each example, and the function name as function. The kind, the source, and the frame location are kept whatever the setting says.

Rather than leave a missing message ambiguous, the evidence carries either a message or a detail note saying why there is none:

A payload holds at most 20 client error insights, the most-reported first.

These are the only insights whose grouping key is partly the browser’s to choose. source and frame are page-determined text, where every other insight groups on server-derived, cardinality-capped values, so a script calling the collector’s endpoint directly with a distinct frame per report could otherwise fill the payload with one group per report and bury the real findings.

Groups are ranked by occurrences before the cut, with ties going to the most recent, which is what makes the cap useful rather than arbitrary: a flood of crafted reports is one occurrence per group, while the error real users keep hitting is many.

The cap applies to the payload only. vaadin.client.errors still counts every report, and vaadin.observability.insights-capacity still governs how many are retained.

Browser errors are retained in their own buffer, separate from the interactions and the data provider queries, so the flood of reports that arrives when a network outage ends can’t evict the failed interactions. With all three collectors active, the total retained is three times the capacity.

In a standalone deployment, use the matching ObservabilitySettings builder methods, and read the buffer through ObservabilityKit.getRecentClientErrors() to render the payload yourself with an InsightsService.

The two describe the same reports and answer different questions:

Nothing in a browser error reaches a tracing span: the failure happened in the browser, so there is no server-side observation to attach it to. For the counter and its tags, see Reference.

3483974E-8425-4430-BE29-1B6A531EF4D8