All jobs

Add Global Error Handling to TanStack Query

Yes. The agent maps what each failed query shows today, routes first-load errors to error boundaries and background ones to a toast, and tests both paths.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent begins by finding out what a user sees today when a request fails, since that is rarely what the code suggests. In an app like alan2207/bulletproof-react (apps/react-vite, @tanstack/react-query 5), src/lib/react-query.ts sets retry: false and carries a commented-out throwOnError: true. Errors are handled in one place, the Axios response interceptor in src/lib/api-client.ts: it adds an error notification for every failed response and sends the browser to the login page on a 401. No component reads isError or error from a query. What happens next depends on how the query was reached. The three list routes fetch in a clientLoader with fetchQuery or fetchInfiniteQuery, which reject, so a failure during navigation replaces the whole dashboard with the root route's ErrorBoundary and its one line, Something went wrong.

A component rendered without that loader behaves differently. comments-list.tsx checks isLoading and then whether there are comments, so when GET /comments answers 500 it shows the toast and, under it, No Comments Found; the users and discussions lists return null without data and render nothing. There is also an error boundary that looks as if it covers this: src/app/routes/app/discussions/discussion.tsx wraps <Comments> in one whose fallback reads Failed to load comments. A failed query does not throw during render unless it is told to, so that fallback cannot appear. The agent writes the test that shows it, using the repository's own renderApp helper, which renders a component with no loader: override the handler with a 500 through the MSW server and assert on which message is in the document. It fails on the current code and becomes the first acceptance test.

The fix follows the split TanStack Query 5 is built for, where useQuery no longer takes an onError callback. A query with nothing to show throws to the nearest boundary: throwOnError: (error, query) => query.state.data === undefined in the default options. A query that already has data and fails on a refetch keeps showing that data and raises one toast, from onError on a QueryCache passed to the QueryClient in src/app/provider.tsx, guarded by the opposite condition. Mutations get the same through MutationCache. The interceptor keeps the 401 redirect and stops raising notifications, so a failure is reported once and not twice. Boundaries are wrapped with QueryErrorResetBoundary so their retry button refetches instead of re-rendering the same error.

Two details decide whether the change is pleasant to live with. Retries: the agent replaces retry: false with a function that retries a network error or a 5xx twice and never a 4xx, and keeps retries off under import.meta.env.TEST, the flag the mock handlers already use, so a test for a failing request does not sit through the backoff. Types: it registers AxiosError as defaultError through the library's Register interface, so error.response?.status type-checks in the retry function and the cache callbacks without casts. In the discussion route's clientLoader it fetches the comments with prefetchInfiniteQuery, which never rejects, so a comments failure no longer takes the discussion down with it and the boundary around <Comments> finally has work to do. The discussion itself still rejects to the route boundary, since there is no page without it.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Give this app one consistent way to handle failed TanStack Query requests. Read the QueryClient setup and default options, the API client and its interceptors, every query and mutation hook, the components that render them, every error boundary and the route loaders first. Install dependencies, create .env from .env.example, and record the type check, lint and test results before changing anything. For each query, write down what the user sees today when the request fails on first load and when a refetch fails with data already on screen; include any error boundary that can never render. Add a failing test for the worst case first, using the existing MSW server to answer 500. Then: make queries with no data throw to the nearest error boundary through a throwOnError function in the default options; report a failed background refetch once, from a QueryCache onError, while keeping the stale data visible; report failed mutations from a MutationCache onError; remove error notifications from the HTTP interceptor but keep its 401 redirect; wrap the boundaries so a retry control refetches. In route loaders, keep rejecting for the data a page cannot render without, and prefetch secondary data without rejecting so its own boundary handles the failure. Replace retry: false with a function that retries network errors and 5xx responses twice and never a 4xx, with retries off in tests. Register the HTTP client's error type as the default error type. Do not add a dependency and do not change the notification component. Add tests for first-load failure, background refetch failure and a failed mutation. Open a pull request with a table of every query and its behaviour before and after, and the type check, lint and test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request centred on three files: the query defaults, the provider that builds the QueryClient, and the API client. The description opens with a table of every query in the app and four columns: what a first-load failure showed before and shows now, and the same for a refetch failure.

It lists each error boundary with whether it could render before the change, and the tests added for the three paths with their output from before and after. Anything deliberately left alone is named: the 401 redirect, the route-level boundary for data a page cannot render without, and the text of the existing fallbacks.

The reviewer's check is the duplicate. With the interceptor and the cache both able to notify, one failed request must produce exactly one message, and the new tests assert the count. They also decide whether a full-page fallback is right for every first load; where a query is secondary to the page, the description shows how to override throwOnError on that one hook.

Run it on every app that swallows request errors

A developer usually arrives at this after an incident in which the API was down and the interface showed empty lists. They send this body to POST /o/{org}/sessions from a terminal or an editor's MCP client and return to the incident follow-up; the pull request is on the session when the run completes. A request_id, a UUID created once for the job, makes a retried call return the same run.

A team with several front ends sends the body once per repository, each with its own request_id. The runs do not share anything, so they can go out together, and a key runs as many at once as its max_concurrent allows while the others wait as queued runs.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

What a user sees when a request fails is a question about the running app, not about the code, and the fixture here shows why: the boundary is in the source and never on the screen. In its own sandbox the agent installs the app, makes the mock API answer 500 and reads the rendered page before and after the change. The commands and their output are kept in the transcript at GET /o/{org}/sessions/{id}/messages, so each row of the before-and-after table can be traced to a test run.

The work also touches every data-fetching screen at once, which is slow to verify by hand and quick to verify by suite. The run goes through the whole list in one sitting while the developer's branch stays untouched, and it returns as a pull request that already carries its tests.

Frequently asked questions

Why not put onError back on each useQuery?

TanStack Query 5 removed that callback from queries, because it ran once per component using the query and produced duplicate side effects. The supported places are the QueryCache and MutationCache callbacks, which run once per failed request, and throwOnError for rendering. The agent uses those and does not rebuild the old pattern with effects.

Will every error now replace the page with a fallback?

No. Only a query with no data throws; one that already rendered keeps its data and reports the failure in a toast. A hook can also opt out with its own throwOnError: false and render an inline message, which the description demonstrates on one query.

Does it work with fetch instead of Axios?

Yes. The cache callbacks and throwOnError do not depend on the HTTP client. What changes is the error type registered as defaultError and how the retry function reads the status, and the agent takes both from your client module.

What about Suspense?

useSuspenseQuery throws to a boundary when it has no data to show, the same rule this design uses, and the provider in bulletproof-react already has a Suspense fallback. Converting hooks to it changes loading states across the app, so the agent treats it as a separate job and says so in the pull request.

More TanStack Query jobs

The same job on other stacks

Keep reading