Better error handling for actions, fetchers, revalidations (unexpected errors and network errors)

[okalil]

This proposal aims to Improve the way actions/fetchers/revalidations errors are handled

Background

React Router currently uses Error Boundaries as a unified way to handle errors that occur in routes, regardless of whether the errors occur in loaders, actions, or the component.

I totally get that, having a single way to do a certain thing makes life easier in many cases.

However, in terms of user experience, using error fallbacks only really makes sense when there is nothing that can be displayed in its place, for example when the error occurs when accessing a new page. In the case of a submission error, on the other hand, replacing the form component with an error fallback seems exaggerated...

Workarounds

The recommended approach has always been to return errors as data and access them directly in the component. To capture any type of error, we could wrap our action code in a try/catch.:

const action = async () => {
  try {
    const post = await createPost(await request.formData())
    throw redirect(`/posts/${post.id}`)
  } catch (error) {
    return handleAnyServerSideError(error)
  }
}

To also handle network errors with server actions in framework mode, we could use clientAction:

const clientAction = async ({ serverAction }) => {
  try {
    return await serverAction()
  } catch (error) {
    return handleAnyErrorIncludingNetworkErrors(error)
  }
}

These approaches generally work, but I have observed at least two limitations:

1. You need to add clientAction to every route: In addition to increasing the js bundle slightly, this requires more effort from the developer to remember to add this so that this type of error is properly handled.
2. It doesn't work well with useRevalidator because that would require adding clientLoader to every route putting try/catch in each of them, and in the navigation flow that would create branching for success/error loader data inside the component

Proposal

Add the following properties to hold the uncaught error without unmounting the route component:

componentProps.actionError
useFetcher().error
useRevalidator().error
useNavigation().error

• When there's an action/fetcher/revalidator error, the state will be 'idle' (same as when there's data).
• If the error happens for an action, a revalidation will not be done (same as current behavior with Single Fetch).
• Loader errors for initial page load and navigations will continue render the error fallback to keep the happy path.
• For network errors in navigations, only the new route's ErrorBoundary would be rendered inside the layout, the layout routes would continue rendered (and useNavigation().error could be used to show a global message if needed)

Alternative API

What if there was an event listener to optionally prevent the error boundary?

<Form
  onError={(event) => {
    event.preventDefault();
    toast.error(isNetworkError(event.error) ? 'Network Error' : 'Unknown Error');
  }}
/>

Kind of similar to what we would do with clientAction, but a possible advantage could be being able to create a reusable Form component with this logic built-in.

Open Questions

1. The error property type should be unknown (aligns with the error type in useRouteError()) or always Error (simpler to use)?
2. Should we continue fallbacking to error boundary if the error property is not used/accessed? (I think this makes sense so the change is opt-in, but I'm afraid it gets confusing)

Related Discussions

remix-run/remix#7688
remix-run/remix#5957
remix-run/remix#4242

[peter-skillmasters]

In another discussion I proposed preventErrorBoundary as an explicit way of enabling this behavior: #10013 (comment)

[afoures]

I think that this use case would be covered by middleware: if you add a client middleware for handling network errors and recommended error handling in your action/loaders (via try/catch), you would be able to do everything you need in user-land

[peter-skillmasters]

As far as I can tell, you can't actually handle the network errors in client middleware:

1. the errors aren't thrown via next()
2. you can't rewrite the response anyway

As mentioned above, the best workaround is clientLoader/clientAction. But:

• a complete solution would require you to implement those for every loader/action
• It's an error that's returned as "data", i.e. useActionData or fetcher.data. IMO, it would be much clearer/explicit as an "error", i.e. useActionError or fetcher.error