SSR query initial state as "error" (e.g. 404)

[Aaronkala]

Hey! Love the library, thanks for all the work you have put into it!

Overview

(I'm not sure if this feature already exists, so posting as a Q&A)

We have a use case where we query some content on the server and based on that query we render either the content of the page or a 404 page.

Currently, I haven't found a way to set a query to an error state for the server side render of the application (using react in this case). The server sends a query and we queryClient.setQueryData if the result is a success and would also like to queryClient.setQueryError (imaginary function) if the we know the query returns a 404.

This would allow rendering the application in the "error" state on the server. Currently the application is always rendered in the "pending" state if no query data is available.

Sandbox

Here's an sandbox that demos this, but fails to render the app in the "error" state on the SSR. Reloading on the "error" page should initially render in the "error" state instead of the "pending" state.

https://stackblitz.com/edit/stackblitz-starters-rjijfw?file=src%2Fpages%2F%5Bid%5D.js

Question

Is there a "blessed" way to instantiate a query in the "error" state initially?

[TkDodo]

errors per se aren't serializable over the wire, that's we we don't dehydrate them. If you want that, you'd need to plug something like superjson into it:

https://tanstack.com/query/latest/docs/framework/react/reference/hydration#limitations

[Aaronkala]

Thanks for the quick answer! Okay yeah makes sense to not do anything by default in this case. Marked the above as the answer: "Currently no built in mechanism, due to errors not being serializable"

So with the options that are currently available we would need to fallback on using the query data to also communicate the error state (either with super json or some custom serialization):

(Simplified example)

const useCustomQuery = () => {
  const result = useQuery<{ status: "success", data: TData } | { status: "error", error: TError }>(
    getQueryKey(),
    queryFn
  );
  
  if (result.status === 'error') {
    return { ...result, isError: true, error: result.data.error, ...otherErrorRelatedOverrides };
  }
  
  return { ...result, data: result.data };
}

In the example above I do a quick "dumb" implementation of what this would look like. There are some challenges with keeping the error logic in sync with the error behaviour in tanstack query e.g. what happens to errors when a query refetch starts etc.. The hook will need to reimplement the error logic from tanstack query for it to be somewhat invisible, or alternatively move the error handling to all callsites of the query ((isError || isQueryResultError) ? showError : showContent).

[Aaronkala]

Have you considered/discussed an option to provide an errorSerializer for queries? I'm, maybe a bit naively, thinking this could provide an opt in mechanism to allow handling errors across the "hydration" boundary.

It would be amazing to be able to use the built in error parameters of tanstack query 🤗

[TkDodo]

we would need to fallback on using the query data to also communicate the error state

no, you can leave the query in error state and serialize the error itself. But note that on the client, an erroneous query will likely refetch right away, giving you a loading state, unless you turn of retryOnMount. It's probably better to use error boundaries with throwOnError.

[Aaronkala]

Okay yeah, read the link you linked with more detail now and got the gist as highlighted in the example:

// server
const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
const serializedState = mySerialize(state) // transform Error instances to objects

// client
const state = myDeserialize(serializedState) // transform objects back to Error instances
hydrate(client, state)

Thanks for this! This was exactly what we were looking for 👏