fix(ui): group failed-query Sentry reports by status and query name (#21475)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The browser app can report errors to Sentry. A final query error
goes to Sentry when it is not an outage, a denial, or a missing item.
> - Every failed API request throws an `ApiError` from the same frames
in `api/client.ts`.
> - Sentry groups errors by stack. Thus all unrelated server failures go
into one issue, titled "ApiError: Internal server error".
> - The report has no route, no query name, and no status. Breadcrumbs
and URLs are removed for privacy. A person cannot find which endpoint
failed.
> - This pull request tags each failed-query report with its HTTP status
and the static name of its query key. It also sets the Sentry
fingerprint from these two values.
> - The benefit: each failing endpoint gets its own Sentry issue, and a
person can connect it to the server error.

## Linked Issues or Issue Description

**What happened?**
One browser Sentry issue collected unrelated server 500 errors from
different pages and environments. The events had no route or query name.
A person could not connect an event to a server error.

**Steps to reproduce**
1. Turn on browser error monitoring with a Sentry DSN.
2. Make two different queries fail with a 500 response, for example the
issues list and the agents list.
3. Look at Sentry. Both events are in one issue with the title
"ApiError: Internal server error". Neither event shows which query
failed.

**Expected behavior**
Each failing query has its own Sentry issue. The event shows the HTTP
status and the static query name. It shows no IDs, refs, or filters.

**Environment**
The hosted browser app, staging and production builds.

I searched open pull requests for duplicates. I found no pull request
that changes browser query-error grouping.

## What Changed

- `ui/src/lib/browser-error-context.ts`: add `queryKindFor`. It keeps
only the first query-key part, and only when it is a lowercase word list
such as `issues` or `agent-commentary`. Other values become `other`, so
an ID, a ref, an email, or a typed value is never sent.
- `ui/src/lib/browser-error-context.ts`: add `buildQueryErrorContext`.
For an error with an HTTP status, it sets the `query_kind` and
`api_status` tags and the fingerprint `["api-error", status,
queryKind]`. For an error without a status, it sets only the
`query_kind` tag and keeps default stack grouping.
- `ui/src/lib/sentry.ts`: add `captureQueryException`. It uses the same
serialized queue as `captureBrowserException`. Both functions now share
one private capture step.
- `ui/src/lib/query-client.ts`: `reportError` now also receives the
query key.
- `ui/src/main.tsx`: the query client reports through
`captureQueryException`.
- Tests for key sanitizing, the fingerprint, the reporter argument, and
the gate call.

## Verification

- Red before the fix: the 6 new assertions fail on the old source
(`queryKindFor`, `buildQueryErrorContext` and `captureQueryException` do
not exist, and `reportError` gets no key).
- Green after the fix: `cd ui && npx vitest run src/lib/sentry.test.ts
src/lib/browser-error-context.test.ts src/lib/query-client.test.ts`
passes 3 files and 78 tests.
- The privacy test makes sure that `company-uuid` and `PAP-1` from later
key parts do not go into the Sentry call. It also makes sure that UUID,
ref, email, and long heads become `other`.
- `ui` typecheck: no errors in the changed files. The local install was
filtered to the UI package, so unrelated packages (`plugin-sdk` build
output, runner dependencies) could not resolve. Required CI supplies the
full typecheck.
- I did not run browser e2e suites. This change does not touch them.

## Risks

- Low risk. Only the grouping and tags of browser query-error reports
change. The app does not change what it shows to users.
- Sentry opens new issues for future query errors, one for each status
and query name. The old catch-all issue gets no new events.
- A query key with a dynamic first part becomes `other`. Those errors
still group together, but they keep the status tag.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use, repository inspection, and shell code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Devin FoleyandClaude Opus 5.5 authored and GitHub committed 2026-11-13 12:24:46 -08:00
1 parent ef2a49b6df
commit f58bbefc4e
7 files changed
+130 -13

No files matched your search

+30
View File
@@ -4,6 +4,8 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import {
__resetPageDiagnostics,
buildBrowserErrorContext,
buildQueryErrorContext,
queryKindFor,
readPageLifecycle,
sanitizeComponentStack,
startPageDiagnostics,
@@ -17,6 +19,34 @@ afterEach(() => {
document.documentElement.className = "";
});
describe("query error context", () => {
it("keeps only a static query key name", () => {
expect(queryKindFor(["issues", "company-uuid", "detail", "PAP-1"])).toBe("issues");
expect(queryKindFor(["agent-commentary", "company-uuid"])).toBe("agent-commentary");
expect(queryKindFor(["266ff1d0-6be9-47cb-b2ed-300fce5fbcd3"])).toBe("other");
expect(queryKindFor(["abcdefab-abcd-4bcd-abcd-abcdefabcdef"])).toBe("other");
expect(queryKindFor(["PAP-1"])).toBe("other");
expect(queryKindFor(["person@example.com"])).toBe("other");
expect(queryKindFor(["a".repeat(65)])).toBe("other");
expect(queryKindFor([{ companyId: "company-uuid" }])).toBe("other");
expect(queryKindFor([])).toBe("other");
});
it("fingerprints an HTTP failure by status and query name", () => {
const error = Object.assign(new Error("Internal server error"), { status: 500 });
expect(buildQueryErrorContext(error, ["issues", "company-uuid"])).toEqual({
tags: { query_kind: "issues", api_status: "500" },
fingerprint: ["api-error", "500", "issues"],
});
});
it("keeps default stack grouping for an error without an HTTP status", () => {
expect(buildQueryErrorContext(new TypeError("x is undefined"), ["issues"])).toEqual({
tags: { query_kind: "issues" },
});
});
});
describe("browser error context", () => {
it("keeps React component names without locations or unrecognized content", () => {
const stack = `
+33
View File
@@ -1,3 +1,5 @@
import { errorStatus } from "@/api/errors";
export interface BrowserErrorDetails {
boundary: "app" | "route";
componentStack?: string | null;
@@ -167,6 +169,37 @@ export function __resetPageDiagnostics() {
lastRejection = undefined;
}
const QUERY_KIND_PATTERN = /^[a-z]+(?:[-_][a-z]+)*$/;
const MAX_QUERY_KIND_LENGTH = 64;
/**
* The query key's static name, such as `issues`. Later key parts hold
* companies, refs and filters, and are never read. A head with a digit,
* uppercase letter or other character can be an ID or a typed value, so it
* becomes `other`.
*/
export function queryKindFor(queryKey: readonly unknown[]): string {
const head = queryKey[0];
return typeof head === "string" && head.length <= MAX_QUERY_KIND_LENGTH && QUERY_KIND_PATTERN.test(head)
? head
: "other";
}
/**
* Every failed request throws from the same `ApiError` frames, so default
* grouping puts all of them in one Sentry issue. Group an HTTP failure by its
* status and query name instead, so each failing endpoint has its own issue.
*/
export function buildQueryErrorContext(error: unknown, queryKey: readonly unknown[]) {
const queryKind = queryKindFor(queryKey);
const status = errorStatus(error);
if (status === null) return { tags: { query_kind: queryKind } };
return {
tags: { query_kind: queryKind, api_status: String(status) },
fingerprint: ["api-error", String(status), queryKind],
};
}
/** A bounded snapshot, taken at the error rather than when the capture queue runs. */
export function buildBrowserErrorContext(details: BrowserErrorDetails) {
const componentStack = sanitizeComponentStack(details.componentStack);
+3 -2
View File
@@ -73,14 +73,14 @@ describe("createAppQueryClient", () => {
let client: QueryClient;
let unbind: () => void;
let notifyMutationError: ReturnType<typeof vi.fn<(toast: MutationErrorToast) => void>>;
let reportError: ReturnType<typeof vi.fn<(error: unknown) => void>>;
let reportError: ReturnType<typeof vi.fn<(error: unknown, queryKey: readonly unknown[]) => void>>;
beforeEach(() => {
vi.useFakeTimers();
probe = vi.fn<() => Promise<ProbeResult>>().mockResolvedValue({ reachable: false, retryAfterMs: null });
store = createConnectivityStore({ probe, browserOnline: true });
notifyMutationError = vi.fn<(toast: MutationErrorToast) => void>();
reportError = vi.fn<(error: unknown) => void>();
reportError = vi.fn<(error: unknown, queryKey: readonly unknown[]) => void>();
client = createAppQueryClient({ connectivity: store, notifyMutationError, reportError });
client.mount();
unbind = bindConnectivity(client, store);
@@ -275,6 +275,7 @@ describe("createAppQueryClient", () => {
await observer.refetch();
expect(queryFn).toHaveBeenCalledTimes(2);
expect(reportError).toHaveBeenCalledTimes(1);
expect(reportError).toHaveBeenCalledWith(expect.any(ApiError), ["broken"]);
unsubscribe();
});
+3 -2
View File
@@ -116,7 +116,8 @@ export interface MutationErrorToast {
export interface AppQueryClientDeps {
connectivity: Pick<ConnectivityStore, "reportError" | "getSnapshot">;
reportError?: (error: unknown) => void;
/** Report a final query error. The key lets the reporter group by query name. */
reportError?: (error: unknown, queryKey: QueryKey) => void;
/** Show a toast for a failed opted-in mutation that has no handler of its own. */
notifyMutationError?: (toast: MutationErrorToast) => void;
}
@@ -178,7 +179,7 @@ export function createAppQueryClient(deps: AppQueryClientDeps, config: QueryClie
const last = lastReportedAt.get(query.queryHash);
if (last !== undefined && now - last < QUERY_ERROR_REPORT_WINDOW_MS) return;
lastReportedAt.set(query.queryHash, now);
deps.reportError(error);
deps.reportError(error, query.queryKey);
},
});
const mutationCache = new MutationCache({
+30
View File
@@ -319,6 +319,36 @@ describe("captureBrowserException", () => {
});
});
describe("captureQueryException", () => {
it("does not throw when the gate is closed", async () => {
const { captureQueryException } = await importFreshSentry();
expect(() => captureQueryException(new Error("boom"), ["issues"])).not.toThrow();
});
it("groups each failing query's server error by status and query name", async () => {
const mocks = mockSentryPackage();
const { initBrowserErrorMonitoring, captureQueryException } = await importFreshSentry();
await initBrowserErrorMonitoring(DSN);
const issuesError = Object.assign(new Error("Internal server error"), { status: 500 });
const agentsError = Object.assign(new Error("Internal server error"), { status: 500 });
captureQueryException(issuesError, ["issues", "company-uuid", "detail", "PAP-1"]);
captureQueryException(agentsError, ["agents", "company-uuid"]);
await initBrowserErrorMonitoring(DSN);
expect(mocks.captureException).toHaveBeenNthCalledWith(1, issuesError, {
tags: { query_kind: "issues", api_status: "500" },
fingerprint: ["api-error", "500", "issues"],
});
expect(mocks.captureException).toHaveBeenNthCalledWith(2, agentsError, {
tags: { query_kind: "agents", api_status: "500" },
fingerprint: ["api-error", "500", "agents"],
});
expect(JSON.stringify(mocks.captureException.mock.calls)).not.toMatch(/company-uuid|PAP-1/);
});
});
describe("browser error diagnostics with the real SDK", () => {
it("emits bounded component and translation context without page data or scope leakage", async () => {
const Sentry = await vi.importActual<typeof import("@sentry/browser")>("@sentry/browser");
+29 -7
View File
@@ -16,12 +16,12 @@
// as long as the close call takes. Both calls are built-in Sentry client
// calls — no custom filter code.
//
// `initBrowserErrorMonitoring`, `teardownBrowserErrorMonitoring`, and
// `captureBrowserException` each queue their work on one shared promise
// chain (`enqueue`) instead of running at once. One operation runs at a
// time, in call order, so no operation can ever observe another one
// part-finished — a sign-out always closes the client a sign-in already
// finished starting, never one still starting.
// `initBrowserErrorMonitoring`, `teardownBrowserErrorMonitoring`,
// `captureBrowserException`, and `captureQueryException` each queue their
// work on one shared promise chain (`enqueue`) instead of running at once.
// One operation runs at a time, in call order, so no operation can ever
// observe another one part-finished — a sign-out always closes the client a
// sign-in already finished starting, never one still starting.
//
// `@sentry/browser` loads through a dynamic import, so Vite puts it in a
// separate chunk that a browser with no DSN never fetches.
@@ -40,6 +40,7 @@
import {
buildBrowserErrorContext,
buildQueryErrorContext,
classifyRejectionReason,
readBrowserErrorState,
readPageLifecycle,
@@ -157,13 +158,34 @@ export function captureBrowserException(error: unknown, details?: BrowserErrorDe
} catch {
// Diagnostics must never replace the original exception or its recovery UI.
}
enqueueCapture(error, context);
}
/**
* Report a failed query, grouped by its HTTP status and the static name of
* its query key. Never throws, and is a no-op until the gate opens.
*/
export function captureQueryException(error: unknown, queryKey: readonly unknown[]): void {
let context: ReturnType<typeof buildQueryErrorContext> | undefined;
try {
context = buildQueryErrorContext(error, queryKey);
} catch {
// Diagnostics must never replace the original exception.
}
enqueueCapture(error, context);
}
function enqueueCapture(
error: unknown,
context: ReturnType<typeof buildBrowserErrorContext> | ReturnType<typeof buildQueryErrorContext> | undefined,
): void {
void enqueue(async () => {
try {
if (context) sentry?.captureException(error, context);
else sentry?.captureException(error);
} catch (err) {
// eslint-disable-next-line no-console
console.error("[paperclip] Sentry captureBrowserException failed", err);
console.error("[paperclip] Sentry captureException failed", err);
}
});
}
+2 -2
View File
@@ -30,7 +30,7 @@ import { getOrCreatePaperclipReactRoot } from "./lib/react-root";
import { startServiceWorkerUpdates } from "./lib/service-worker-updates";
import { connectivity } from "./lib/connectivity";
import { bindConnectivity, createAppQueryClient } from "./lib/query-client";
import { captureBrowserException } from "./lib/sentry";
import { captureQueryException } from "./lib/sentry";
import { startPersistedQueryCache } from "./lib/persisted-query-cache";
import { hasPendingWrites, subscribePendingWrites } from "./lib/reload-safety";
import "@mdxeditor/editor/style.css";
@@ -65,7 +65,7 @@ function MutationErrorToastBridge() {
const queryClient = createAppQueryClient(
{
connectivity,
reportError: (error) => captureBrowserException(error),
reportError: (error, queryKey) => captureQueryException(error, queryKey),
notifyMutationError: ({ title, body }) => pushMutationErrorToast?.({ title, body, tone: "error" }),
},
{