Handling Errors with Suspense | Effect Atom

In the previous chapter, we created a Suspense-enabled UserGrid component. However, we didn’t handle errors. If the data fetch fails, useAtomSuspense throws the error and the app crashes.

To catch these errors and prevent crashes, React provides Error Boundaries. They wrap a section of your component tree and display a fallback UI when any child component throws.

Using React Error Boundary

First, install the react-error-boundary package:

1
pnpm add react-error-boundary

Create a new file components/error-fallback.tsx:

1
"use client";
2

3
import type { FallbackProps } from "react-error-boundary";
4

5
import { FailureCard } from "@/components/failure-card";
6

7
import { getErrorInfo } from "@/lib/utils";
8

9
export function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
10
  const { title, message } = getErrorInfo(error);
11

12
  return (
13
    <FailureCard title={title} message={message} onRetry={resetErrorBoundary} />
14
  );
15
}

Now update app/page.tsx to wrap the Suspense boundary with an Error Boundary:

1
"use client";
2

3
import { Suspense } from "react";
4
import { useAtomRefresh } from "@effect-atom/atom-react";
5
import { ErrorBoundary } from "react-error-boundary";
6
import { Link } from "react-transition-progress/next";
7

8
import { ErrorFallback } from "@/components/error-fallback";
9
import { UserGridSpinner } from "@/components/user-grid-spinner";
10
import { UserGridSuspense } from "@/components/user-grid-suspense";
11
import { UserPagination } from "@/components/user-pagination";
12
import { UserSearchBar } from "@/components/user-search-bar";
13

14
import { usersAtom } from "@/atoms/user";
15

16
export default function HomePage() {
17
  const refreshUsers = useAtomRefresh(usersAtom);
18

19
  return (
20
    <div className="container max-w-5xl space-y-10">
21
      <div className="flex items-center justify-between">
22
        <h1>Users</h1>
23
        <Link
24
          href="/add-user"
25
          className="bg-accent text-foreground px-4 py-2 text-sm font-medium transition-colors hover:bg-neutral-200"
26
        >
27
          + Add User
28
        </Link>
29
      </div>
30
      <UserSearchBar />
31
      <ErrorBoundary FallbackComponent={ErrorFallback} onReset={refreshUsers}>
32
        <Suspense fallback={<UserGridSpinner />}>
33
          <UserGridSuspense />
34
        </Suspense>
35
      </ErrorBoundary>
36
      <UserPagination />
37
    </div>
38
  );
39
}

The Error Boundary wraps the Suspense boundary. If the data fetch fails, the Error Boundary catches the error and renders ErrorFallback instead of crashing the app.

Notice that we use the useAtomRefresh hook. This hook takes an Atom and returns a function that, when called, tells the Registry to invalidate the Atom and re-run its Effect. We store this function in refreshUsers.

We then pass refreshUsers as the onReset prop of the ErrorBoundary. When the user clicks the retry button in ErrorFallback, it calls resetErrorBoundary, which does two things. First, it resets the Error Boundary’s internal state so it attempts to render its children again. Second, it triggers the onReset callback, which calls refreshUsers to re-run the usersAtom’s Effect. Without onReset, the Error Boundary would try to re-render the children, but the Atom’s failed result would still be cached. It would throw the same error again immediately.

To see the Error Boundary in action, go to services/user-service.ts and change the endpoint from /users to /usersx (an endpoint that doesn’t exist). Visit the home page. You’ll see the ErrorFallback component rendered with the error title and message. Click the retry button. Since the endpoint is still invalid, you’ll see the error again.

Handling Errors Manually

If you prefer to handle errors within the component rather than using an Error Boundary, useAtomSuspense accepts an includeFailure option.

First, remove the ErrorBoundary wrapper and the related imports from app/page.tsx:

1
"use client";
2

3
import { Suspense } from "react";
4
import { useAtomRefresh } from "@effect-atom/atom-react";
5
import { ErrorBoundary } from "react-error-boundary";
6
import { Link } from "react-transition-progress/next";
7

8
import { ErrorFallback } from "@/components/error-fallback";
9
import { UserGridSpinner } from "@/components/user-grid-spinner";
10
import { UserGridSuspense } from "@/components/user-grid-suspense";
11
import { UserPagination } from "@/components/user-pagination";
12
import { UserSearchBar } from "@/components/user-search-bar";
13

14
import { usersAtom } from "@/atoms/user";
15

16
export default function HomePage() {
17
  const refreshUsers = useAtomRefresh(usersAtom);
18

19
  return (
20
    <div className="container max-w-5xl space-y-10">
21
      <div className="flex items-center justify-between">
22
        <h1>Users</h1>
23
        <Link
24
          href="/add-user"
25
          className="bg-accent text-foreground px-4 py-2 text-sm font-medium transition-colors hover:bg-neutral-200"
26
        >
27
          + Add User
28
        </Link>
29
      </div>
30
      <UserSearchBar />
31
      <ErrorBoundary FallbackComponent={ErrorFallback} onReset={refreshUsers}>
32
        <Suspense fallback={<UserGridSpinner />}>
33
          <UserGridSuspense />
34
        </Suspense>
35
      </ErrorBoundary>
36
      <UserPagination />
37
    </div>
38
  );
39
}

Now replace the code inside components/user-grid-suspense.tsx with the following:

1
"use client";
2

3
import { useAtomRefresh, useAtomSuspense } from "@effect-atom/atom-react";
4
import { Cause } from "effect";
5

6
import { FailureCard } from "@/components/failure-card";
7
import { UserSuccessCard } from "@/components/user-success-card";
8

9
import { getErrorInfo } from "@/lib/utils";
10
import { usersAtom } from "@/atoms/user";
11

12
export function UserGridSuspense() {
13
  const result = useAtomSuspense(usersAtom, { includeFailure: true });
14
  const refresh = useAtomRefresh(usersAtom);
15

16
  if (result._tag === "Failure") {
17
    const error = Cause.squash(result.cause);
18
    const { title, message } = getErrorInfo(error);
19

20
    return <FailureCard title={title} message={message} onRetry={refresh} />;
21
  }
22

23
  return (
24
    <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
25
      {result.value.users.map((user) => (
26
        <UserSuccessCard key={user.id} user={user} />
27
      ))}
28
    </div>
29
  );
30
}

With includeFailure: true, the useAtomSuspense hook returns the Failure result instead of throwing. This gives you full control over how errors are displayed.

Cause.squash extracts the underlying error from the Cause. This is necessary because Effect wraps errors in a Cause type that can represent complex error scenarios like multiple failures or interruptions.

For the retry button, we use useAtomRefresh — the same hook we used in the Error Boundary approach. We refresh usersAtom because it’s the Atom that runs the Effect to fetch users’ data. Once usersAtom refreshes, usersListAtom, being a derived Atom, updates automatically.

If you still have the endpoint set to /usersx, visit the home page. You’ll see the FailureCard component rendered with the error details and a retry button, handled entirely within the component rather than by an Error Boundary.

Note

Before continuing, make sure to revert the users endpoint back to /users in services/user-service.ts.

Using React Error Boundary

Handling Errors Manually

Stay in the loop