Network Error Handling

[sergiodxa]

Proposal

Add a way to handle network errors from within the Remix app.

Background

Right now, if there's a network error while Remix does a request to the server there's no way to handle it. This is a problem because if the user has any connectivity issue the app will fail, this is even worst in the case of actions where the form UI will be replaced by the nearest ErrorBoundary and the user will lose any change, unless of course the app saves them to localStorage.

This is based on a conversation here #5957 (comment).

Use Case

• Prevent submissions if there's no connectivity.
• Handle failed navigations
• Handle failed submissions without losing input values
• Handle failed revalidations

API/Examples

Handle lack of connectivity

With the useNetworkStatus hook applications should be able to handle lack of connectivity and prevent submissions.

The hook will return a NetworkStatus interface.

// This is an interface so it can later be extended with more information like connection type, save-data mode, etc.
interface NetworkStatus {
  status: "online" | "offline";
}

declare function useNetworkStatus(): NetworkStatus;

This can be used to disable a button if it's offline:

import { useNetworkStatus } from "@remix-run/react";

export default function Component() {
  let networkStatus = useNetworkStatus();

  let isOffline = networkStatus.status === "offline";

  return (
    <Form method="post">
      <input type="hidden" name="id" value="123" />
      <button disabled={isOffline}>Like</button>
    </Form>
  );
}

Or to prevent form submissions and maybe warn the user.

import { useNetworkStatus } from "@remix-run/react";

export default function Component() {
  let networkStatus = useNetworkStatus();

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    if (networkStatus.status === "online") return;
    event.preventDefault();
    alert("You're offline, please check your connection and try again.");
  }

  return (
    <Form method="post" onSubmit={handleSubmit}>
      <input type="hidden" name="id" value="123" />
      <button>Like</button>
    </Form>
  );
}

Handle global network errors (Form/useSubmit)

If we don't prevent the submission at all, the request may fail, the useNetworkError hook should let use get the error and handle it.

// There's always the error thrown by `fetch`
type NetworkError = { error: Error } & (
  | { type: "revalidation" } // only type is added for revalidations
  // If the error happened during a navigation, the location will be set
  | { type: "navigation"; location: Location }
  // If the error happened during a submission, the form* will be set too
  | {
      type: "submission";
      formEncType?: Submission["formEncType"];
      formAction?: Submission["formAction"];
      formMethod?: Submission["formMethod"];
      formData?: Submission["formData"];
      json: Submission["json"];
      text: Submission["text"];
    }
);

declare function useNetworkError(): NetworkError | undefined;

Then we can use it to show a toast or something.

import { useNetworkError } from "@remix-run/react";

export default function Component() {
  let networkError = useNetworkError();
  let toast = useToast();

  useEffect(() => {
    if (!networkError) return;
    toast("Please check your connection and try again.");
  }, [toast, networkError]);

  // JSX of a form
}

We could also save the user data

import { useNetworkError } from "@remix-run/react";

export default function Component() {
  let networkError = useNetworkError();

  useEffect(() => {
    if (!networkError) return;
    if (networkError.type !== "submission") return;
    // save the form data to sessionStorage
    sessionStorage.setItem("form", serialize(networkError.formData));
  }, [networkError]);

  // JSX of a form
}

Or you could retry the submission:

import { useNetworkError } from "@remix-run/react";

export default function Component() {
  let networkError = useNetworkError();
  let submit = useSubmit();

  useEffect(() => {
    if (!networkError) return;
    if (networkError.type !== "submission") return;
    // retry the submission
    submit(networkError.formData ?? networkError.json, {
      action: networkError.formAction,
      method: networkError.formMethod,
      encType: networkError.formEncType,
    });
  }, [networkError, submit]);

  // JSX of a form
}

And because you have access to the Error object you can also throw it to the ErrorBoundary if you prefer.

import { useNetworkError } from "@remix-run/react";

export default function Component() {
  let networkError = useNetworkError();

  // just throw it to the ErrorBoundary, maybe ensure it was caused by a specific form
  if (networkError) throw networkError.error;

  // JSX of a form
}

Handle network errors in Fetchers

Since fetchers can be sent in parallel, each fetcher should come with its own network error object.

import { useFetcher } from "@remix-run/react";

export default function Component() {
  let fetcher = useFetcher();

  useEffect(() => {
    // The fetcher.state now includes `networkError`
    if (fetcher.state !== "networkError") return;
    // access formData the same way as right now
    sessionStorage.setItem("form", serialize(fetcher.formData));
    // retry the submission
    submit(networkError.formData ?? networkError.json, {
      action: networkError.formAction,
      method: networkError.formMethod,
      encType: networkError.formEncType,
    });
  }, [fetcher]);

  // Here fetcher.networkError is the error instance
  if (fetcher.state === "networkError") throw fetcher.networkError;

  // JSX of a form
}

Note
In this part I'm not 100% sure about the API, but my overall idea is to expose the same information but as part of the fetcher object following the current convention as much as possible.

[dmarkow]

This would resolve a lot of errors and poor user experience in our app. As @sergiodxa mentioned we could use localStorage to save form state, but that gets very cumbersome in an app of our size (700 routes). In some things, like background logging, we've had to go back to just using plain fetch calls instead of useFetcher so we could let it silently fail instead of blowing up the page.

Alternatively, something like an onError callback to useFetcher could work too. Related react-router discussion/proposal.

[rubber-duck-software]

See my comment over here #7634 (comment)

I'm thinking clientLoader and clientAction might provide a clean solution to this. To handle the general case, maybe need clientMiddleware??? 🤔 If you wanted to handle all network error in your app the same, it would be a shame to have repeat your clientAction in every file...

[gabimor]

This is really relevant for me right now. My API returns a 500 or 400 and I just wanna display that in a modal, without the ErrorBoundary blowing away the page, so that the user can close the modal, make some adjustments and try again.
I can't even get the response code (400, 500 etc) from the the useFetcher response. this is really frustrating

[sergiodxa]

Note that an API returning a 400 or 500 is not a network error, a network error is when the request can't even reach the server because the network failed, if you received a response regardless of the status code, it's still a success request, @kettanaito has a great article about this https://kettanaito.com/blog/why-fetch-promise-doesnt-reject-on-error-responses.

So even with this proposal, you will need to handle the 400 and 500 yourself.

[gabimor]

thanks for clarifing sergio!
So not entirely related to your poposal but still in the area:)
Still wondering how to handle application errors concerning the server, like showing a modal with the error on response code other than 200, usually send with a fetcher. I have 2 problems here:

1. I cant get the response code from my fetcher. is that available anywhere?
2. after the modal closes, I need a way to "reset" the fetcher state once so it won't show again on the next render

I have a feeling I'm missing something, a bit like inventing the wheel here. but I couldn't find a clear example for handling errors if I don't wanna use ErrorBounderies which blow out the page state (my app is kind of SPA so the page is everything)

thanks for taking the time to read!

[sergiodxa]

1. The status code is not available, instead ensure the response body has a way to know if it was a success or not, I usually add a type: "error" as const so I can later do data.type === "error"
2. There's no way to reset the fetcher, instead unmount the modal, so next time you mount it it will have a new fetcher

[UltraWelfare]

I'd like to add my input too on this.

I'm in the same realm of wanting to access the status code but instead of a fetcher inside an action. Why?
A user submits a form inside a modal. The action gets called

export async function action({
                                 request
                             }: ActionFunctionArgs) {
    const data = await request.json();
    const result = await createSomething(data);
    if (result.isErr()) {
        return json({ errors: result.errors }, { status: 400 });
    }
    return null;
}

Before I go on I'd like to mention that in various parts of the remix documentation (such as form validation) for some reason it just mentions return json({ errors }); which I find a bit odd.
I'd prefer the response of the action to be a Bad Request 400 with errors rather than a OK 200 with errors... This ties closely to the HTTP standard.

However useActionData gives you only the data itself (the object part) without any way of accessing the status code of the response it self. That means I'd have to add a success field (or something similar) to indicate what has happened. While this is trivial and not a big deal it would be nice if we could do something like:

// imaginary component

const { data, response } = useActionData<typeof action>();
useEffect(() => {
    if(response?.statusCode === 400) {
        // validation failure, show toast, close the modal or do whatever
    } else {
        // handle accordingly
    }
}, [response]);

[brophdawg11]

My biggest issue with an approach like this is that Components today are happy path - i.e., you are guaranteed that useLoaderData is populated if the Component renders. I don't like the idea of breaking that concept and introducing forking for the unhappy path:

export default function Component() {
  let data = useLoaderData();
  let networkError = useNetworkError();

  if (networkError) {
    // unhappy path
  } else if (data) {
    // happy path
  }
}

I think this API is somewhat less concerning for fetchers since they are already conditional on having data by default. I don't know that I'd want to introduce another state - but maybe a flag to treat errors as "data". That's what we tell people to do today when they want to display contextual errors (return json({ ok: false, error: "whatever" })) - so it aligns with the concept of "data" is displayed in your Component, "errors" are displayed in the ErrorBoundary. Then we could treat network errors in a custom error subclass like we do with isRouteErrorResponse.

let fetcher = useFetcher();

// If you specify bubbleErrors: false, then it's on you to branch accordingly
fetcher.load('/', { treatErrorsAsData: true })

if (!fetcher.data) {
  // fetcher is idle/loading
} else if (isNetworkError(fetcher.data)) {
  // never reached the loader
} else if (isRouteErrorResponse(fetcher.data)) {
  // loader throw a Response
} else if (fetcher.data instanceof Error) {
  // loader threw and Error
} else {
  // loader returned data
}

A few related proposals:

• Catching errors on useFetcher #4242
• Custom useFetcher error handling #4645
• API for hooking into `useFetcher` lifecycle. Ex: `useFetcher({onSuccess, onError, ...})` react-router#10013

Also worth noting that once client data lands, you'll be able to do this manually on a per-route basis by converting your errors to data (this would apply to both fetchers and navigational loaders/actions):

async function clientLoader({ serverLoader }) {
  try {
    let res = await serverLoader();
    return res;
  } catch (e) {
    // catch network errors and return them as data
    return { ok: false, error: e }
  }
}

[sergiodxa]

If I understood correcly from the client data RFC, if a route has a clientLoader that should suspend the route when doing SSR, right? So that would mean any route with a <Form> where you want to handle network errors would need a clientLoader losing the SSR of that route until JS runs and the clientLoader can call serverLoader.

[brophdawg11]

We need to add the latest to the RFC, but that's going to end up being opt-in behavior, not the default.

By default, clientLoader will behave as it does in Remix today and it will not run on hydration and only on subsequent navigations. It'll be an optimization for caching, skipping the Remix hop in a BFF setup ,etc. (Every remix route has an internal "client loader" today for the fetch call to the server - they just don't run on hydration because we already have the data)

If you need the route to render a fallback because clientLoader supplements the server loader data such that you can't render the Component until it runs, you'll opt in by providing a fallback element and then we'll server-render the fallback and wait for the client loader to run on hydration before rendering the Component.

[alexanderson1993]

This approach makes a lot of sense to me. I assume the clientLoader fallback element will still have access to the server data, right?