Solid Errors Error Handling

solid-errors-error-handling

Quick Reference

ErrorBoundary

Suspense

What ErrorBoundary Catches vs Does NOT Catch

Critical Warnings

NEVER rely on try/catch for rendering errors -- SolidJS rendering is compiled to direct DOM operations. A try/catch in a component body runs once during setup and CANNOT catch errors that occur later in reactive updates.

NEVER throw errors inside an ErrorBoundary fallback function expecting the SAME boundary to catch them -- errors in the fallback propagate to the PARENT boundary. If no parent boundary exists, the error is uncaught.

ALWAYS wrap components using createResource in BOTH <Suspense> AND <ErrorBoundary> -- Suspense handles loading states while ErrorBoundary handles fetch failures.

ALWAYS place <ErrorBoundary> OUTSIDE <Suspense> when protecting against resource errors -- if ErrorBoundary is inside Suspense, a resource error may not display the error fallback correctly.

NEVER assume createEffect errors are caught during SSR -- createEffect NEVER runs during SSR. Use isServer checks for server-side error handling.

ErrorBoundary Patterns

Static Fallback

import { ErrorBoundary } from "solid-js";

<ErrorBoundary fallback={<p>Something went wrong.</p>}>
  <App />
</ErrorBoundary>

Fallback with Error Details and Reset

import { ErrorBoundary } from "solid-js";

<ErrorBoundary
  fallback={(err: Error, reset: () => void) => (
    <div class="error-panel">
      <h2>Error occurred</h2>
      <p>{err.message}</p>
      <button Again</button>
    </div>
  )}
>
  <DataView />
</ErrorBoundary>

When reset() is called, ErrorBoundary clears its error state and re-renders its children from scratch.

Nested Boundaries

Inner boundaries catch first. If the inner boundary's fallback itself throws, the error propagates to the outer boundary:

<ErrorBoundary fallback={<p>App-level error</p>}>
  <Header />
  <ErrorBoundary
    fallback={(err, reset) => (
      <div>
        <p>Section error: {err.message}</p>
        <button
      </div>
    )}
  >
    <DataSection />
  </ErrorBoundary>
  <Footer />
</ErrorBoundary>

If <DataSection /> throws, only the inner boundary activates. <Header /> and <Footer /> remain visible.

Suspense Patterns

Basic Resource Loading

import { Suspense, createResource } from "solid-js";

const [data] = createResource(fetchData);

<Suspense fallback={<LoadingSpinner />}>
  <DataDisplay data={data()} />
</Suspense>

Suspense vs Show

ALWAYS use <Suspense> for createResource loading states. NEVER use <Show> as a loading gate for resources -- it destroys and recreates the entire subtree, losing state.

Nested Suspense (Independent Loading)

<Suspense fallback={<HeaderSkeleton />}>
  <Header user={userResource()} />

  <Suspense fallback={<ContentSkeleton />}>
    <Content data={dataResource()} />

    <Suspense fallback={<CommentsSkeleton />}>
      <Comments comments={commentsResource()} />
    </Suspense>
  </Suspense>
</Suspense>

Each boundary resolves independently -- the header shows as soon as userResource resolves, without waiting for content or comments.

Suspense Timing

• onMount inside Suspense runs AFTER resources resolve
• createEffect inside Suspense runs AFTER resources resolve
• Both fallback and children branches exist in memory simultaneously
• Fallback is removed and children are attached once ALL tracked resources resolve

ErrorBoundary + Suspense Composition

Standard Pattern: ErrorBoundary Outside Suspense

import { ErrorBoundary, Suspense, createResource } from "solid-js";

const [data] = createResource(fetchData);

<ErrorBoundary
  fallback={(err, reset) => (
    <div>
      <p>Failed to load: {err.message}</p>
      <button
    </div>
  )}
>
  <Suspense fallback={<LoadingSpinner />}>
    <DataDisplay data={data()} />
  </Suspense>
</ErrorBoundary>

Why this order: When a resource rejects, the error propagates upward. ErrorBoundary outside Suspense catches it and displays the error fallback. If ErrorBoundary were inside Suspense, the Suspense boundary would not know to stop showing its fallback.

Error Recovery with Resource Refetch

import { ErrorBoundary, Suspense, createResource } from "solid-js";

function DataPanel() {
  const [data, { refetch }] = createResource(fetchData);

  return (
    <ErrorBoundary
      fallback={(err, reset) => (
        <div>
          <p>Error: {err.message}</p>
          <button => { reset(); refetch(); }}>
            Retry
          </button>
        </div>
      )}
    >
      <Suspense fallback={<p>Loading...</p>}>
        <div>{data()?.title}</div>
      </Suspense>
    </ErrorBoundary>
  );
}

ALWAYS call both reset() AND refetch() when recovering from resource errors. reset() clears the error state; refetch() re-triggers the data fetch.

Error Recovery Patterns

Reset + State Reset

import { ErrorBoundary, createSignal } from "solid-js";

function RecoverableForm() {
  const [formData, setFormData] = createSignal({ name: "", email: "" });

  return (
    <ErrorBoundary
      fallback={(err, reset) => (
        <div>
          <p>Form error: {err.message}</p>
          <button => {
            setFormData({ name: "", email: "" });
            reset();
          }}>
            Reset Form
          </button>
        </div>
      )}
    >
      <FormContent data={formData()} />
    </ErrorBoundary>
  );
}

catchError (Programmatic Error Handling)

import { catchError, createEffect } from "solid-js";

function MonitoredComponent() {
  catchError(
    () => {
      createEffect(() => {
        // Reactive computation that might fail
        riskyOperation();
      });
    },
    (err) => {
      console.error("Caught in reactive scope:", err);
      reportToErrorService(err);
    }
  );
}

catchError provides programmatic error handling within reactive scopes without rendering a fallback UI. Use it for logging, reporting, or silent recovery.

Server-Side Considerations

• createEffect NEVER runs during SSR -- errors in effects are client-only
• Suspense on the server enables streaming HTML -- resources resolve server-side
• ErrorBoundary works during SSR for synchronous rendering errors
• ALWAYS use isServer from solid-js/web when error handling logic differs between server and client

Decision Tree

Choosing an Error Handling Strategy

Is the error from a reactive computation or rendering?
├── YES → Use <ErrorBoundary>
│   ├── Need error details + retry? → fallback={(err, reset) => ...}
│   ├── Simple error display? → fallback={<ErrorMessage />}
│   └── Need programmatic handling too? → Add catchError inside
└── NO (event handler, setTimeout, etc.)
    └── Use standard try/catch in the handler

Choosing Loading State Strategy

Is data from createResource?
├── YES → Use <Suspense>
│   ├── Multiple independent resources? → Nested <Suspense> boundaries
│   ├── Resource might fail? → Wrap with <ErrorBoundary> OUTSIDE
│   └── Need previous data during refresh? → Use resource.latest
└── NO (signal-based state)
    └── Use <Show when={data()}> for conditional rendering

Reference Links

• references/methods.md -- API signatures for ErrorBoundary, Suspense, catchError
• references/examples.md -- Working code examples for all error handling patterns
• references/anti-patterns.md -- What NOT to do, with explanations

Official Sources

• https://docs.solidjs.com/reference/components/error-boundary
• https://docs.solidjs.com/reference/components/suspense
• https://docs.solidjs.com/reference/basic-reactivity/create-resource