Error Handling for Mutations

[rubber-duck-software]

Proposal

Allow action errors to be handled without unmounting the route's default component.

Background

In a traditional SPA, a very common error handling pattern for mutations is something like this

"If the mutation throws an error, we show the user a dialog which informs them of the failure. When the dialog is dismissed, the user should be seeing their form again still filled out and ready to retry the submission."

This is very user friendly (and relatively common across the web). In a more traditional React SPA, the code to make this happen might look something like

<form onSubmit={async event => {
    event.preventDefault()
    try {
       await fetch('/some-route', { method: 'post' })
    } catch (error) {
       showErrorDialog()
    }
}}>
...
</form>

Accomplishing this same behavior is Remix is currently not possible to my knowledge. Let's say that our user is experiencing network issues when they try to submit a Remix Form. The server will never receive the request and an error will be thrown. There is no opportunity to catch this error in user-land and so Remix renders the ErrorBoundary.

But wait! When we rendered the error boundary, we unmounted the default route component losing all our form data and react state! This is not a good user experience and there are not good workarounds available.

Proposal Details

I propose that the ErrorBoundary should render if there in an error on component render or in the loader for the route, but not if there is an error in the action. The reason for the distinction is that even if the action fails, we can go on rendering the default route component. It still has all it needs to render, so why unmount it?

The UI for an action error should be able to be "added on top of" the existing UI.

Why does this belong in Remix

The Remix docs talk about using progressive enhancement to ensure your UI is resilient to network issues. See https://remix.run/docs/en/1.14.3/tutorials/blog#progressive-enhancement

The Remix docs talk about maintaining form state in case of server error (does not mention network errors). See https://remix.run/docs/en/1.14.3/guides/optimistic-ui#maintain-form-state

I think allowing users to maintain form state while being resilient to network issues is a very natural fit.

Possible APIs

These are just my initial thoughts

1. useActionError

export default function MyRoute() {
    const actionError = useActionError()
    
    return (
        <div>
            <Form>
                ...
            </Form>
            {actionError ? <span>sorry try again</span> : null}
       </div>
    )
}

2. ActionErrorOutlet

export default function MyRoute() {
    return (
        <div>
            <Form>
                ...
            </Form>
            <ActionErrorOutlet />
       </div>
    )
}

[kiliman]

I commented on your previous post before reading this proposal. I like it. I think it should be opt-in, though. Something like:

<Form handleError />

[kentcdodds]

Right, and in those cases you get to manage that in your action so you can send a response and get it in the useActionData.

Again, I'm pretty sure this issue is only really about handling when making a network call to the action fails. Situations in which our action code is never even called and therefore our action code can't provide error messages.

[lili21]

to do this, we have to using try catch in every action ,

export const action = async () => {
  try {
    await callAnotherService();
    return json({ success: true });
  } catch (e) {
    return json({ success: false, reason: e.message }, { status: 500 });
  }
}

and don't forget the status code option, cause in production, we need to know how many api call are failed and do some metrics and alerting.

in this way, why don't just let the action throw?

[lili21]

I think it's the same problem, what should we do to handle the action exception?
is there any case the we want the page/ui fallback to ErrorBoundary/CatchBoundary because of user click a submit button?

[rubber-duck-software]

The original nature of this proposal was

Allow action errors to be handled without unmounting the route's default component.

Which is currently impossible in case of a network error and (I believe) not very ergonomic in case of an error thrown in the action. At first, I was expecting the same API change to handle both of these cases, but am now realizing that these cases could be handled separately.

Assuming that we go forward with useNetworkError for handling network errors, I have created a new discussion for improving the ergonomics of handling errors thrown in actions. See #6008.

To ensure the API for handling network errors ends up in the right place, I think we should (at least briefly) indulge a discussion about making handling action errors more ergonomic. It is possible, but not necessary, that these apis are related.

[lili21]

maybe we can do it with fetcher.submit or submit return from useSubmit?.

Using the <Form /> if you want something more like browser behavior and works even it's not hydrated yet, and when the action failed, the exception captured by boundary.

Using fetcher.submit if you want do it in another way, we can provide a promise based API

fetcher.submit()
  .then(() => {
  })
  .catch(() => {
    // handle the exception, it can be the network error, or the action just failed.
  });

[rubber-duck-software]

@kiliman - let me see if I understand you. Would the api be something like below?

<Form handleError={e => /* handle the error */} />

and then the default implementation for handleError would be to simply throw the error.

And for the use case I described above would be implemented as

<Form handleError={e => showErrorDialog()} />

[kiliman]

Yeah, I'm not keen on the name. I probably shouldn't have used "handle" since I'm not saying it should be an event handler, but simply a marker that I opt-in to manually handling errors via useActionError or ActionErrorOutlet. In other words, the default should be how Remix currently handles errors.

[rubber-duck-software]

As I think about it, why not an event handler? An event handler might be the most flexible for developers to use. If developers were given an event handler, they could easily implement their own versions of useActionError or ActionErrorOutlet.

But, honestly, I'm not familiar enough with the Remix code base to know what is possible. I could also see

<Form errorHandling="throw" /> // the default
<Form errorHandling="manual" /> // opting into custom error handling UI

[lili21]

we ran into the same issue so many times.

[lili21]

we need this.

[lili21]

especial for fetcher.load and fetcher.submit, no reason this fetching error should unmount entire route.

[scolestock]

Planned as a possibility anytime soon?

[machour]

Linking to remix-run/react-router#10013 as it also addresses the situation

[chrisvltn]

This would be amazing to have. A failure sending a response in a pop-up chat in the corner of the page shouldn't break the whole page. :)

[okalil]

I stopped using actions because of that. But now that clientAction landed, we can probably handle network errors there.

[okalil]

I imagine something like that should work

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

[okalil]

handleNetworkError could trigger the dialog/toast for instance since the function runs on client side

[gitnik]

Is there any news regarding this? It's a major pain point for us.