[dawsontoth]

Stacked on the auth stack: #1813 → #1815 → #1816 → #1854 → this PR. The base is claude/1329-scope-auth-checks-to-org (#1854), so the diff here is only the #1808 work. Merge the stack in order, then retarget this PR to stage. It lands alongside #1809 (stacked on #1804), which it doesn't share a line with — see Landing with #1809.

⊙ Problem

When a page's data fails to load (the org, cluster, or instance registration-info read in a route's beforeLoad or loader), Studio shows the route's error page and also a toast with the same failure in raw server words. React Query's global handler console.errors it as well, which RUM files as a console-sourced error next to the error boundary's own report (#1808). Driving the real router on this base with one org 403 and two reloads gave 3 GETs, 3 toasts and 3 console-sourced reports, on top of the boundary's.

❓ Your call: Is the requirement right as scoped? I think so: the error page already says what happened, and two Error Tracking issues with different fingerprints for one failure hide whether either is getting worse. This PR removes the query-cache half. #1809 removes the boundary half (re-catches, and the root handler's own console.error). It's one report only once both are in, so this body's Closes #1808 should only fire on whichever merges second. Merge this after #1809, or drop that line.

Closes #1808

💡 Solution

• A route read claims its query while the route awaits it. ensureRouteQueryData now takes the route function's own arguments. When the read has to fetch and the call isn't a preload, it claims the query until the read settles or the router aborts the load (claimForRoute).
• queryErrorHandler skips a claimed failure (here): no toast, no console.error. The error page is the one message and the root onCaughtError the one report.
• Everything else is unchanged: a background refetch on a page that rendered, imperative fetches, reads the cache answers, a load the user navigated away from (the router aborts it, which releases the claim), and every preload still toast and report as today.

⚠️ Look hardest: the claim has to be live when React Query reports the failure. QueryCache.onError runs synchronously in the failing Query.fetch's catch, before the rejection reaches the route (query-core 5.104.1 query.ts:799), and the claim is released in finally, after it. A test checks the claim is held at onError time.

Landing with #1809

The two touch no common lines. I merged #1809's head (9581286) into this branch locally, cleanly, and re-ran the route tests with #1809's real reactRootErrorHandlers.onCaughtError and exact counts. One org 403 plus two reloads gave addReactError ×1, console.error ×0, toast ×0, and one "No Access to This Organization" page. Hover-then-click on the org, and a loader read the navigation runs, gave the same. With this PR's handler check removed, the merged tree logs one console report per GET (4), so #1809 alone doesn't get there. tsc -b is clean on the merged tree. Either can merge first.

⚖️ Alternatives

❓ Your call: A navigation adopts a loader its hover preload still has in flight instead of running it again (router-core 1.171.34, verified with the real router). So one path still reports twice: hover an instance link, click before registration info answers, and it fails (toast and console, then the boundary). A test pins it. I don't claim loader preloads. That would close this path but silence every failed hover nobody clicked: the router doesn't log a preload's route failure (load-client.ts:2161), and the planning reviewer and both implementation reviewers flagged that silent case. Closing it with nothing silent means moving registration info from loader to beforeLoad, which a navigation does re-run. Three components read it through useLoaderData, so that's its own change. Either way is easy to revisit.

• The issue's option 1, a query meta flag set by route loads: rejected. meta lives on the shared Query and the last writer wins. When a navigation joins a fetch already in flight (the hover-then-click path), Query.fetch returns the in-flight promise before applying the caller's options (query.ts:594-615), so the flag never lands where it's needed most. The claim is the same explicit, route-only marker, scoped to the load instead of to the query.
• The issue's option 2, skip a failure with no data and no observers: rejected. It also silences fetchQuery/ensureQueryData failures nothing renders (SearchDialog, EditorViewProvider, secrets.ts), dropping their only report.
• Opt the route queries out in their option factories: rejected. The same factories back the polling useQuerys (the org query polls every 10 s), so a background failure would go quiet.
• Dedupe downstream, in beforeSend or the root handler: rejected. The toast stays, and the console event is already sent.
• The planning review (codex) returned better-alternative-exists: don't claim beforeLoad preloads, because a navigation runs beforeLoad again. I adopted it. After implementation round 1, I went further and dropped preload claims entirely.

🔧 Changes

• src/react-query/routeQueryClaims.ts (new): claimForRoute keeps a reference count per Query object in a WeakMap, so overlapping loads of one query (a load plus an invalidate) don't release each other. Release is idempotent and runs from finally or on abort. A load the router already aborted claims nothing. isClaimedByRoute is the handler's check.
• src/react-query/queryClient.ts: queryErrorHandler returns early on a claimed failure, after the restart-noise check. Its doc says why.
• src/router/ensureRouteQueryData.ts: takes a RouteLoad (context, abortController, preload), the subset of TanStack's beforeLoad/loader arguments it needs. The call sites pass the real objects, so a rename upstream breaks the build. It builds the same Query ensureQueryData will and claims only an uncached read. Its doc states the contract: a caller that catches the rejection takes on reporting it. The sign-out cancellation path from fix(router): let a sign-out's cache clear abandon a route load instead of failing it #1816 is unchanged.
• Call sites pass their route arguments: org layout, cluster layout, and the registration-info loader, which now types its argument as RouteLoad plus params.
• src/router/DESIGN.md (new), indexed from the root DESIGN.md: the ownership rule, why preloads don't claim and the adopted-loader duplicate, and a limit. If two parallel loaders in one route chain ever read different queries and both fail, only the rendered failure is reported. Today they all read registration info.

✅ Verification

• End-to-end route — routeLoadFailureReporting.test.tsx drives the real router through the production chain (root → dashboard → orgs → org layout) with the app's queryClient, mocking only apiClient.get and addReactError:
  • A failed org load plus two reloads: no toast, no query-cache console report, boundary fired.
  • Hover preload in flight, then click: one GET, same result.
  • Hover with no click, leaving before the load fails, and a background refetch on a rendered page: toast and report as today, no boundary.
  • With a real loader: the navigation runs it, boundary only; hover with no click, toast and report; adopted from an in-flight preload, still twice.
  • This proves app-to-SDK calls, not delivery to Datadog. After deploy, @error.source:console AxiosErrors per route-load failure should drop to zero.
• Fails on base. With the isClaimedByRoute check removed (the base's handler path), the first e2e test fails with expected [ …4 ] to deeply equal [] (one console report per GET), and 3 more e2e tests plus the unit test go red. Mutations: no abort release turns the navigate-away and abort tests red; claiming preloads turns the hover tests red; claiming cached reads turns the cached-read test red; dropping the reference count turns both overlap tests red.
• Unit. ensureRouteQueryData.test.ts: the claim is held during the await and at onError time, covers the same Query under a custom queryKeyHashFn, is released on abort, and is never taken for a preload or a cached read. The existing sign-out tests run on the new signature. routeQueryClaims.test.ts covers identity, reference counting, abort then release, a late abort, and an already-aborted signal. queryClient.test.ts: a claimed failure gets no toast and no console.error, and gets both once released.
• Composition with Report each failed route load to RUM once, and offer Try Again when the server errors or can't be reached #1809: see Landing with #1809.
• Gates: the pre-commit hook on the head commit ran vitest (405 files, 3,733 tests pass), oxlint, dprint and commitlint, all clean; tsc -b 0. Not checked in a browser: what changes is the toast and console channel, which the jsdom tests observe directly.
• Cross-model review: codex (graded, plus the planning round) and gemini, two implementation rounds. Cursor failed both rounds on the 1Password SSH agent (no-receipt), and the Harper domain leg failed auth (OAuth session expired), so outside findings weren't adjudicated and I triaged them myself. Taken: no preload claims (round 1 major from both — a loader preload's claim silenced hover-only failures and any background fetch it joined), no claim for a cached read (codex minor), and comment trims. Kept open: the adopted-loader duplicate (the ❓ above), and codex's point that the fixture's root handler leaves out this base's console.error. That channel is Report each failed route load to RUM once, and offer Try Again when the server errors or can't be reached #1809's, and the merged-tree run uses the real handler with exact counts. Declined: codex's minor that building the Query before ensureQueryData repeats work. It's once per route read on navigation, next to a network call.

🤖 Generated with Claude Code

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: #1809 overlaps (lands with it: this PR drops the query-cache report, #1809 the boundary's duplicates; no shared lines), #1816 overlaps (stacked on it; changes its helper's signature), 1 others independent
Complexity: complicated

_{Review-Coverage: authored=claude; ran=codex,gemini; blocked=cursor-composer(no-receipt),domain(auth),cursor-muse(no-receipt); declined=cursor-grok,cursor-kimi; rounds=2; full=1 @ 474b549}

_{Review-Attention: study ~9m (raised: degraded review, open blocker) @ 474b549}

[gemini-code-assist]

Code Review

This pull request introduces a query-claiming mechanism during route loading to ensure that route load failures are handled and reported solely by the route's error boundary, suppressing global error toasts and RUM reports for active route loads. It refactors ensureRouteQueryData to accept a RouteLoad context, implements query tracking in routeQueryClaims.ts, and updates the global query error handler to respect these claims. Comprehensive unit and integration tests, along with design documentation, have been added to verify the new behavior. I have no additional feedback to provide as there are no review comments to address.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	68.18%	10261 / 15049
🔵	Statements	68.31%	10942 / 16018
🔵	Functions	61.55%	2647 / 4300
🔵	Branches	62.97%	7773 / 12343

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/cluster/clusterLayoutRoute.ts	100%	100%	100%	100%
src/features/instance/registrationInfoLoader.ts	100%	100%	100%	100%
src/features/organization/routes.ts	76.19%	50%	63.63%	76.19%	24, 35, 41, 48, 54
src/react-query/queryClient.ts	97.95%	97.67%	83.33%	97.95%	83
src/react-query/routeQueryClaims.ts	100%	90%	100%	100%
src/router/ensureRouteQueryData.ts	100%	100%	100%	100%

Generated in workflow #2155 for commit 33b0f43 by the Vitest Coverage Report Action