React error page

If you like this article please support me by checking out Pull Reminders, a Slack bot that sends your team automatic reminders for GitHub pull requests.

One challenge I recently ran into while working with GraphQL and React was how to handle errors. As developers, we’ve likely implemented default 500, 404, and 403 pages in server-rendered applications before, but figuring out how to do this with React and GraphQL is tricky.

In this post, I’ll talk about how our team approached this problem, the final solution we implemented, and interesting lessons from the GraphQL spec.

Background

The project I was working on was a fairly typical CRUD app built in React using GraphQL, Apollo Client, and Express GraphQL. We wanted to handle certain types of errors — for example, the server being down — by displaying a standard error page to the user.

Our initial challenge was figuring out the best way to communicate errors to the client. GraphQL doesn’t use HTTP status codes like 500, 400, and 403. Instead, responses contain an errors array with a list of things that went wrong (read more about errors in the GraphQL spec).

For example, here’s what our GraphQL response looked like when something broke on the server:

{
  "errors": [
    {
      "message": "TypeError: Cannot read property 'name' of undefined",
      "locations": [
        {
          "line": 2,
          "column": 2
        }
      ],
      "path": [
        "program"
      ]
    }
  ],
  "data": {
    "program": null
  }
}

Since GraphQL error responses return HTTP status code 200, the only way to identify the kind of error was to inspect the errors array. This seemed like a poor approach because the error message was the message from the exception thrown on the server. The GraphQL spec states that the value of message is intended for developers, but it does not specify whether the value should be a human-readable message or something designed to be programmatically handled:

Every error must contain an entry with the key message with a string description of the error intended for the developer as a guide to understand and correct the error.

Adding Error Codes to GraphQL Responses

To solve for this, we added standardized error codes to our error objects, which could be used by clients to programmatically identify errors. This was inspired by how Stripe’s REST API returns string error codes in addition to human-readable messages.

We decided on three error codes to start: authentication_error, resource_not_found, and server_error.

To add these to our GraphQL responses, we passed our own formatError function to graphql-express that maps exceptions thrown on the server to standard codes which get added to the response. The GraphQL spec generally discourages adding properties to error objects, but does allow for it by nesting those entries in an extensions object.

const formatError = (error) => {
  const { constructor } = error.originalError;

  let code;

  switch (constructor) {
    case AuthorizationError:
      code = 'authorization_error';
    case ResourceNotFound:
      code = 'resource_not_found';
    default:
      code = 'server_error';
  }

  return {
    extensions: {
      code
    },
    ...error
  };
};

app.use('/graphql', (req, res) => graphqlHTTP({
  schema,
  graphiql: config.graphiql,
  context: { req, res },
  formatError
})(req, res));

Our GraphQL response errors were then easy to classify:

{
  "errors": [
    {
      "message": "TypeError: Cannot read property 'name' of undefined",
      "locations": [
        {
          "line": 2,
          "column": 2
        }
      ],
      "path": [
        "program"
      ],
      "extensions": {
        "code": "server_error"
      }
    }
  ],
  "data": {
    "program": null
  }
}

While we developed our own way of adding codes to responses generated by express-graphql, apollo-server appears to offer similar built-in behavior.

Rendering error pages with React Error Boundaries

Once we figured out a good way of handling errors in our server, we turned our attention to the client.

By default, we wanted our app to display a global error page (for example, a page with the message “oops something went wrong”) whenever we encountered a server_error, authorization_error, or authorization_not_found. However, we also wanted the flexibility to be able to handle an error in a specific component if we wanted to.

For example, if a user was typing something into a search bar and something went wrong, we wanted to display an error message in-context, rather than flash over to an error page.

To achieve this, we first created a component called GraphqlErrorHandler that would sit between apollo-client’s Query and Mutation components and their children to be rendered out. This component checked for error codes in the response threw an exception if it identified a code we cared about.

import React from 'react';
import {
  ServerError,
  AuthorizationError,
  ResourceNotFound
} from '../errors';

const checkFor = (code, errors) => errors && errors.find( e => e.extensions.code === code);

const checkError = ({ networkError, graphQLErrors }) => {
  // networkError is defined when the response is not a valid GraphQL response, e.g. the server is completely down
  if ( networkError ) {
    throw new ServerError();
  }

  if (checkFor('server_error', graphQLErrors)) {
    throw new ServerError();
  }

  if (checkFor('authorization_error', graphQLErrors)) {
    throw new AuthorizationError();
  }

  if (checkFor('resource_not_found', graphQLErrors)) {
    throw new ResourceNotFound();
  }
};

const GraphqlErrorHandler = ({ error, children }) => {
  if (error) checkError(error);
  return children;
};

export default GraphqlErrorHandler;

To use the GraphqlErrorHandler, we wrapped apollo-client’s Query and Mutation components:

import React from 'react';
import Query from 'Components/graphql/Query';
import GET_PROGRAM from './queries/getProgram';
import ViewProgram from './ViewProgram';

const ViewProgramContainer = (props) => {
  const { programCode } = props.match.params;

  return (
    <Query query={GET_PROGRAM} variables={{ programCode }}>
      {({ loading, data, }) => (
        <ViewProgram program={data.program} loading={loading} />
      )}
    </Query>
  );
};

export default ViewProgramContainer;

Now that our React app was throwing exceptions when the server returned errors, we wanted to handle these exceptions and map them to the appropriate behavior.

Remember from earlier that our goal was to default to displaying global error pages (for example, a page with the message “oops something went wrong”), but still have the flexibility to handle an error locally within any component if we desired.

React error boundaries provide a fantastic way of doing this. Error boundaries are React components that can catch JavaScript errors anywhere in their child component tree so you can handle them with custom behavior.

We created an error boundary called GraphqlErrorBoundary that would catch any server-related exceptions and display the appropriate error page:

import React from 'react';
import ServerErrorPage from 'Components/errors/ServerError';
import NotFoundPageErrorPage from 'Components/errors/NotFound';
import UnauthorizedErrorPage from 'Components/errors/Unauthorized';
import {
  ServerError,
  AbsenceError,
  AuthorizationError,
  ResourceNotFound
} from '../errors';

class GraphqlErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      error: null
    };
  }

  componentDidCatch(error) {
    if ( error.name === AuthorizationError.name ) {
      this.setState({ error: AuthorizationError.name });
    } else if ( error.name === ServerError.name ) {
      this.setState({ error: ServerError.name });
    } else if ( error.name === ResourceNotFound.name ) {
      this.setState({ error: ResourceNotFound.name });
    } else {
      this.setState({ error: ServerError.name });
    }
  }

  render() {
    if (this.state.error === ServerError.name ) {
      return <ServerErrorPage />
    } else if (this.state.error === AuthorizationError.name) {
      return <UnauthorizedErrorPage />
    } else if (this.state.error === ResourceNotFound.name) {
      return <NotFoundErrorPage />
    }
    return this.props.children;
  }
}

export default GraphqlErrorBoundary;

We then wrapped our app’s components with this error boundary:

const App = () => {
  return (
    <div className='appContainer'>
      <Header />
      <GraphqlErrorBoundary>
        <Routes />
      </GraphqlErrorBoundary>
      <Footer />
    </div>
  );
};

If we wanted to handle errors within a specific component instead of rendering an error page, we could turn that component into an error boundary. For example, here’s what it’d look if we wanted custom error handling behavior in our component from earlier:

import React from 'react';
import Query from 'Components/graphql/Query';
import GET_PROGRAM from './queries/getProgram';
import ViewProgram from './ViewProgram';

class ViewProgramContainer extends React.Component {
  componentDidCatch(error) {
    if (error.name === ServerError.name) {
      // do something
    }
  }

  render() {
    const { programCode } = this.props.match.params;

    return (
      <Query query={GET_PROGRAM} variables={{ programCode }}>
        {({ loading, data, }) => (
          <ViewProgram program={data.program} loading={loading} />
        )}
      </Query>
    );
  }
}

export default ViewProgramContainer;

Wrap up

GraphQL is still relatively new, and error handling is a common challenge that developers seem to be running into. By using standardized error codes in our GraphQL responses, we can communicate errors to clients in a useful and intuitive way. In our React apps, error boundaries provide a great way to standardize our app’s error handling behavior while still having flexibility when we need it.

Let’s face it. Nobody wants to see a broken, empty page while surfing the web. It leaves you stranded and confused. You don’t know what happened or what caused it, leaving you with a bad impression of the website.

It is often better to communicate the error and let the user continue to use the app. The user will get less of a bad impression and can continue to use its features.

In today’s post, we’ll go through different ways to handle errors in React applications.

The Classic ‘Try and Catch’ Method in React

If you’ve used JavaScript, you’ve probably had to write a ‘try and catch’ statement. To make sure we’re on board with what it is, here’s one:

try {
  somethingBadMightHappen();
} catch (error) {
  console.error("Something bad happened");
  console.error(error);
}

It is a great tool to catch misbehaving code and ensure our app doesn’t blow up into smithereens. To be more realistic and close to the React world as possible, let’s see an example of how you’d use this in your app:

const fetchData = async () => {
  try {
    return await fetch("https://some-url-that-might-fail.com");
  } catch (error) {
    console.error(error); // You might send an exception to your error tracker like AppSignal
    return error;
  }
};

When doing network calls in React, you’d usually use the try...catch statement. But why? Unfortunately, try...catch only works on imperative code. It does not work on declarative code like the JSX we are writing in our components. So that is why you don’t see a massive try...catch wrapping our whole app. It just won’t work.

So, what do we do? Glad you asked. In React 16, a new concept got introduced — React Error Boundaries. Let’s dig into what they are.

React Error Boundaries

Before we get into error boundaries, let us first see why they are necessary. Imagine you had a component like this:

const CrashableComponent = (props) => {
  return <span>{props.iDontExist.prop}</span>;
};
 
export default CrashableComponent;

If you try to render this component somewhere, you’ll get an error like this one:

Not only that, the whole page will be blank, and the user won’t be able to do or see anything. But what happened? We tried to access a property iDontExist.prop, which doesn’t exist (we don’t pass it to the component). This is a banal example, but it shows that we cannot catch these errors with the try...catch statement.

This whole experiment brings us to error boundaries. Error boundaries are React components that catch JavaScript errors anywhere in their child component tree. Then, they log those caught errors and display a fallback UI instead of the component tree that crashed. Error boundaries catch errors during rendering, in lifecycle methods, and in constructors of the whole tree below them.

An error boundary is a class component that defines either (or both) of the lifecycle methods static getDerivedStateFromError() or componentDidCatch().
static getDerivedStateFromError() renders a fallback UI after an error has been thrown.
componentDidCatch() can log error information to your service provider (like AppSignal) or to a browser console.

Here’s an example of how information about a React error looks in AppSignal’s ‘issue list’:

Let’s see a typical error boundary component:

import { Component } from "react";
 
class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  static getDerivedStateFromError(error) {
    // Update state so the next render will show the fallback UI.
    return {
      hasError: true,
      error,
    };
  }
 
  componentDidCatch(error, errorInfo) {
    // You can also log the error to an error reporting service like AppSignal
    // logErrorToMyService(error, errorInfo);
  }
 
  render() {
    const { hasError, error } = this.state;
 
    if (hasError) {
      // You can render any custom fallback UI
      return (
        <div>
          <p>Something went wrong 😭</p>
 
          {error.message && <span>Here's the error: {error.message}</span>}
        </div>
      );
    }
 
    return this.props.children;
  }
}
 
export default ErrorBoundary;

We can use ErrorBoundary like so:

<ErrorBoundary>
  <CrashableComponent />
</ErrorBoundary>

Now, when we open our app, we will get a working app with the following:

That is precisely what we want. We want our app to remain functional when an error occurs. But we also want to inform the user (and our error tracking service) about the error.

Beware that using an error boundary is not a silver bullet. Error boundaries do not catch errors for:

• Event handlers
• Asynchronous code (e.g. setTimeout or requestAnimationFrame callbacks)
• Server-side rendering
• Errors that are thrown in the error boundary itself (rather than its children)

You still need to use the try...catch statement for these fellas. So, let’s go ahead and show how you can do that.

Error Catching in Event Handlers

As mentioned before, error boundaries can’t help us when an error is thrown inside an event handler. Let’s see how we can handle those. Below is a small button component that throws an error when you click it:

import { useState } from "react";
 
const CrashableButton = () => {
  const [error, setError] = useState(null);
 
  const handleClick = () => {
    try {
      throw Error("Oh no :(");
    } catch (error) {
      setError(error);
    }
  };
 
  if (error) {
    return <span>Caught an error.</span>;
  }
 
  return <button onClick={handleClick}>Click Me To Throw Error</button>;
};
 
export default CrashableButton;

Notice that we have a try and catch block inside handleClick that ensures our error is caught. If you render the component and try to click it, this happens:

We have to do the same in other cases, like in setTimeout calls.

Error Catching in setTimeout Calls

Imagine we have a similar button component, but this one calls setTimeout when clicked. Here’s how it looks:

import { useState } from "react";
 
const SetTimeoutButton = () => {
  const [error, setError] = useState(null);
 
  const handleClick = () => {
    setTimeout(() => {
      try {
        throw Error("Oh no, an error :(");
      } catch (error) {
        setError(error);
      }
    }, 1000);
  };
 
  if (error) {
    return <span>Caught a delayed error.</span>;
  }
 
  return (
    <button onClick={handleClick}>Click Me To Throw a Delayed Error</button>
  );
};
 
export default SetTimeoutButton;

After 1,000 milliseconds, the setTimeout callback will throw an error. Luckily, we wrap that callback logic in try...catch, and setError in the component. That way, no stack trace is shown in the browser console. Also, we communicate the error to the user. Here’s how it looks in the app:

That is all well and good, as we got our app’s pages up and running despite errors popping all over the place in the background. But is there an easier way to handle errors without writing custom error boundaries? You bet there is, and of course, it comes in the form of a JavaScript package. Let me introduce you to the react-error-boundary.

JavaScript’s react-error-boundary Package

You can pop that library inside your package.json faster than ever with:

npm install --save react-error-boundary

Now, you’re ready to use it. Remember the ErrorBoundary component we made? You can forget about it because this package exports its own. Here’s how to use it:

import { ErrorBoundary } from "react-error-boundary";
import CrashableComponent from "./CrashableComponent";
 
const FancyDependencyErrorHandling = () => {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onError={(error) => {
        // You can also log the error to an error reporting service like AppSignal
        // logErrorToMyService(error, errorInfo);
        console.error(error);
      }}
    >
      <CrashableComponent />
    </ErrorBoundary>
  );
};
 
const ErrorFallback = ({ error }) => (
  <div>
    <p>Something went wrong 😭</p>
 
    {error.message && <span>Here's the error: {error.message}</span>}
  </div>
);
 
export default FancyDependencyErrorHandling;

In the example above, we render the same CrashableComponent, but this time, we use the ErrorBoundary component from the react-error-boundary library. It does the same thing as our custom one, except that it receives the FallbackComponent prop plus the onError function handler. The result is the same as we had with our custom ErrorBoundary component, except you don’t have to worry about maintaining it since you’re using an external package.

One great thing about this package is that you can easily wrap your function components into a withErrorBoundary making it a higher-order component (HOC). Here’s how that looks:

import { withErrorBoundary } from "react-error-boundary";
 
const CrashableComponent = (props) => {
  return <span>{props.iDontExist.prop}</span>;
};
 
export default withErrorBoundary(CrashableComponent, {
  FallbackComponent: () => <span>Oh no :(</span>,
});

Nice, you’re good to go now to capture all those errors bugging you.

But maybe you don’t want another dependency in your project. Can you achieve it yourself? Of course you can. Let’s see how it can be done.

Using Your Own React Boundaries

You can achieve a similar, if not the same, effect you get from react-error-boundary. We already showed a custom ErrorBoundary component, but let’s improve it.

import { Component } from "react";
 
export default class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }
 
  static getDerivedStateFromError(error) {
    // Update state so the next render will show the fallback UI.
    return {
      hasError: true,
      error,
    };
  }
 
  componentDidCatch(error, errorInfo) {
    // You can also log the error to an error reporting service like AppSignal
    // logErrorToMyService(error, errorInfo);
  }
 
  render() {
    const { hasError, error } = this.state;
 
    if (hasError) {
      // You can render any custom fallback UI
      return <ErrorFallback error={error} />;
    }
 
    return this.props.children;
  }
}
 
const ErrorFallback = ({ error }) => (
  <div>
    <p>Something went wrong 😭</p>
 
    {error.message && <span>Here's the error: {error.message}</span>}
  </div>
);
 
const errorBoundary = (WrappedComponent) => {
  return class extends ErrorBoundary {
    render() {
      const { hasError, error } = this.state;
 
      if (hasError) {
        // You can render any custom fallback UI
        return <ErrorFallback error={error} />;
      }
 
      return <WrappedComponent {...this.props} />;
    }
  };
};
 
export { errorBoundary };

Now you get the ErrorBoundary and the HOC errorBoundary that you can use across your app. Extend and play around with it as much as you want. You can make them receive custom fallback components to customize how you recover from each error. You can also make them receive an onError prop and later call it inside componentDidCatch. The possibilities are endless.

But one thing is for sure — you didn’t need that dependency after all. I bet writing your own error boundary will bring a sense of achievement, and you’ll get to understand it better. Also, who knows what ideas you might get when you’re trying to customize it.

Summing Up: Get Started with React Error Handling

Thanks for reading this blog post about handling errors in React. I hope you had as much fun reading and trying things out as I did writing it. You can find all the code, with examples, in the GitHub repo I created.

A quick rundown of the things we went through:

• React Error boundaries are great for catching errors in declarative code (e.g., inside their child component tree).
• For other cases, you need to use a try...catch statement (e.g., async calls like setTimeout, event handlers, server-side rendering, and errors thrown in the error boundary itself).
• A library like react-error-boundary can help you write less code.
• You can also run your own error boundary and customize it as much as you want.

That is all, folks. Thanks for tuning in, and catch you in the next one!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.