Server error handling

[rmarscher]

I'm trying to understand how to gracefully handle exceptions raised on the server.

This document suggests that Suspense components can act as error boundaries for SSR - https://github.com/reactjs/rfcs/blob/main/text/0215-server-errors-in-react-18.md

It would be nice to additionally register a fallback component that would be rendered instead of the error.toString().

I see that both RSC and SSR waku middleware have this in a catch block:

ctx.res.body = stringToStream(`${err}`);

Maybe if I add middleware that runs after the other renderers, I can see if ctx.res is an error response and update the rendered body.

If I can create unlinked router entries for my error pages, then my middleware could use the rsc or ssr renderers to render one of those entries.

Maybe the exported getConfig() for pages could return the name of a fallback error entry point to use if an exception is hit while rendering that page?

[dai-shi]

I would like to understand the problem better. It feels like this should be solved at the low level "minimal" API, not pages.

Is it only about customizing ctx.res.body = stringToStream(${err});?

additionally register a fallback component

so, you want to return something like <div>error...</div>. Any idea how to render it on the client?

[rmarscher]

Yes, I think it is mainly about customizing that error body. It might be useful to have some type of config hook to inject error reporting / instrumentation.

With the minimal API, maybe it could be possible to await the render functions - renderRsc, renderHtml - inside a try/catch and let those error be caught inside the unstable_handleRequest method. Inside the catch, I could run a different render with an error entry point, passing in the exception to my component.

import { new_defineEntries } from 'waku/minimal/server';
import { Slot } from 'waku/minimal/client';

import App from './components2/App';
import ErrorPage from './components2/ErrorPage';
import { runWithRerender } from './als';

export default new_defineEntries({
  unstable_handleRequest: async (input, { renderRsc, renderHtml }) => {
    if (input.type === 'component') {
      try {
        return await renderRsc({ App: <App name={input.rscPath || 'Waku'} /> });
      } catch (e) {
        return await renderRsc({ App: <ErrorPage error={e} /> });
      }
    }
    if (input.type === 'function') {
      try {
        const elements: Record<string, unknown> = {};
        const rerender = (rscPath: string) => {
          elements.App = <App name={rscPath || 'Waku'} />;
        };
        const value = await runWithRerender(rerender, () =>
          input.fn(...input.args),
        );
        return await renderRsc({ ...elements, _value: value });
      } catch (e) {
        const value = {
          error: "",
          ...(hasStatusCode(e) ? { statusCode: e.statusCode } : {}),
        };
        // or `const value = input.error(e, input.args);` ?
        return renderRsc({ _value: value });

        // I think something like causes the client to replace the app
        // with the error page which might not be desirable.
        const elements: Record<string, unknown> = {};
        const rerender = (rscPath: string) => {
          elements.App = <ErrorPage error={e} />;
        };
        const value = await runWithRerender(rerender, () =>
          input.error(e, input.args),
        );
        return renderRsc({ ...elements, _value: value });
      }
    }
    if (input.type === 'custom' && input.pathname === '/') {
      try {
        return await renderHtml({ App: <App name="Waku" /> }, <Slot id="App" />, '');
      } catch (e) {
        return await renderHtml({ App: <ErrorPage error={e} /> }, <Slot id="App" />, '');
      }
    }
  },
  unstable_getBuildConfig: async () => [
    { pathname: '/', entries: [{ rscPath: '' }] },
  ],
});

[dai-shi]

wow, it's nice to see you are following the latest new_defineEntries.

I think one idea would be something like this:

      } catch (e) {
        const errElement = <ErrorPage err={e} />;
        return renderRsc({ _err: e, Err: errElement });
      }

It's still just an idea.

[rmarscher]

I'm trying to keep up! 😅 🏃 🚀

Yes, passing the error and component is a good idea. That would give more options to the client for handling the exception.

[rmarscher]

I wonder if it would be useful to have a way to tap into the react-dom/server.edge renderToReadableStream onError when it is run in a react-server environment. https://react.dev/reference/react-dom/server/renderToReadableStream#logging-crashes-on-the-server I'm not sure if React has docs on the react-dom-server-webpack renderToReadableStream - but I see it has a third options param that seems to take an onError callback.

These docs say to wrap renderToReadableStream in a try/catch block for errors that happen outside a Suspense boundary. https://react.dev/reference/react-dom/server/renderToReadableStream#recovering-from-errors-inside-the-shell

I'm trying to follow what happens in the waku handler middleware... the renderToReadableStream promise gets passed to the streamFromPromise util which has a try/catch block and calls the error method on the stream.

With Waku server, I think the intent is that those errors on the body stream would trigger the Hono server onError handler? https://hono.dev/docs/api/exception#handling-httpexception

I am enhancing hono from waku config with an onError handler that looks at the request url. I have it look at c.req.header("accept") and return a fallback html error page if it accepts text/html and otherwise return a text error message and a 500 error code <-- I think when that happens with RSC, it might cause React to render Internal Server Error on the page.

I also see that React documents Suspense as the way to handle server errors. The server should render the Suspense fallback on error. And then the client would hit the same error on hydration which would then get trapped by the nearest error boundary. It's great that you got react-error-boundary working "out of the box" from npm. https://react.dev/reference/react-dom/server/renderToReadableStream#recovering-from-errors-outside-the-shell

I wonder if our default create-waku template should include an error boundary. The default <h1>Not Found</h1> is pretty confusing because the place that's rendering it is deep in the Waku source and not documented. It's easy to hit that error - create a waku project, open the home page in the browser, stop the dev server, click the link to navigate to the About page. If we add a Suspense and ErrorBoundary component to the default layout, that might help people understand how to customize that behavior.

[dai-shi]

Oh, this involves quite a lot of things. It's not just one fix, I'd assume. Those are all good points and invalidate my previous comments.

The most important one should be:

The server should render the Suspense fallback on error. And then the client would hit the same error on hydration which would then get trapped by the nearest error boundary.

Can you help by creating a small example that shows how this should work in this regard?
It can be in ./examples or ./e2e, or just a standalone stackblitz.

[dai-shi]

These docs say to wrap renderToReadableStream in a try/catch block for errors that happen outside a Suspense boundary.

For such errors, I think it should be 500 response. I wonder how we should integrate it with Hono capability, but it's a separate/additional issue to revisit later.

The default <h1>Not Found</h1> is pretty confusing

Do you mean it shows Not Found even if it's truly Not Found? That was my concern too and should be fixed. There's a bad hack assuming if 404 for unknown errors. This might be a separate issue or tied to <Suspense> with errors.

If we add a Suspense and ErrorBoundary component to the default layout, that might help people understand how to customize that behavior.

Yeah, that should be great.

[rmarscher]

Thank you. I will work on an example that simulates different error conditions.

[rmarscher]

I did a bit of work on this to add e2e tests. #1112