[Handling Errors] - In production mode, explicit error messages for server components

[Julien-Goletto]

Summary

Context :

NextJS 14.0.3, Typescript, App router
Separated backend API (Django Rest Framework)
Contenerized deployment with docker/docker-compose on a Ubuntu server.
Local dev environment : WSL 2 (Ubuntu), locally deployed contenerized API.

In this application, I wanted to handle errors almost identically, wether they are client or server side.
If client side errors are emitted, I intercept them and play various effects, such as toasting the error message.
As for server components, I use the errors boundaries as per design :

'use client';
import React from 'react';
import type { Metadata } from 'next';
import { ErrorContent } from '@/app/components/atomic';

export const metadata: Metadata = {
  title: 'My Title',
  description: 'Something went wrong',
};

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return <ErrorContent {...{ error, reset }} />;
}

As I could'nt extend the Error class to create a custom HttpError class (with status property for instance) and use the extended class with a error.tsx file, I found this kind of work around, aggregating the status in the error message :

import React from 'react';
import { cookies } from 'next/headers';
import { ssrRequest } from '@/utils';
import { Schema, shipDefaultValuesSchema } from '@/schemas';
import type { Metadata } from 'next';
import { notFound } from 'next/navigation';

export const generateMetadata = async ({
  searchParams,
}: {
  searchParams: { ship_id: string };
}): Promise<Metadata> => {
  try {
    const id = searchParams.id;
    const data= await ssrRequest(
      `${process.env.API_URL}/sata/${id}`,
      schema,
      'GET',
      cookies()
    );
   return data;
    };
  } catch (error) {
    if (error instanceof Error) {
      if (error.message.includes('404')) return notFound();
      throw error;
    }
    throw new Error('Metadata generation failed');
  }
};

NextJS censors error message outputs in production as follow :
An error occurend in the Server Component render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additionnal details about the nature of the error.
Error digest : XXXXXXXXXXXXX

As I control all kind of emitted errors and some contain essential feedbacks for the user, I wonder if there is a way to perform a clean error handling for server components.

Additional information

No response

Example

No response

[tocaherge]

Losing a bit of hope with the lack of official information or responses on this matter, basically all threads I follow on error tracking are dead ends...

[Julien-Goletto]

It's turning me crazy : how such a major topic could have that little coverage ?
Both community / official contents are dodging the bullet.
Are people really shipping NextJS apps in production... ?

[tocaherge]

The only way I've found as a "working" setup is having a hacky monkeypatch of the internal logging to forward it to DataDog and then when I get errors or reports of errors I just go have a look in the logs there...
Posted more details in this comment: #47563 (reply in thread)

Another thread I've opened on the subject, to no avail: #61572

[SouthLink]

You can probably use sentry to enhance access to error information by listening for errors in server components and server action
https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/#report-react-component-render-errors

[tocaherge]

That's not an option in my projects - and not a reasonable solution for all cases.

[leerob]

Can you walk me through a product UI example and the intended output? It sounds like you want to catch an error on the server, and then display that message to the client. Is this for that case, or is it about unhandled exceptions? To confirm, this is not about just viewing the server-side error logs?

[leerob]

There's two sides here: uncaught exception (error reporting), which should use error.tsx, and generalized, caught errors, which should use useFormState/ useActionState. The latter is how you can take complete control over what the application displays and what information you pass to the client, in response from your server action.

[Julien-Ose]

Putting aside server actions particular case, my initial intent was dealing with purposely thrown errors in server components, intercepted by errors boundaries.

Error messages obfuscation in production does not allow us to rely on it for providing consistent feedbacks to our users, unless I missed a point.

[tocaherge]

For example to safeguard fetching of something from an API I would need to do something like this now, simplified example:

async function getData(): Promise<{ data: SomeData | null, error?: string }> {
  try {
    const apiClient = new ApiClient();
    const data = await apiClient.fetchSomeData({});
    return { data };
  } catch (error) {
    return { data: null, error };
  }
}

export default async function Page() {
  const { data, error } = await getData();

  if (!data) {
    return <ErrorDisplay error={error} />
  }

  return (
    <DataDisplay data={data} />
  );
}

When instead it feels like I would much rather have getData throw whatever error it wants to, depending on the response—then an error.tsx for this page, parallel route, or a parent global boundary would "catch" this error and display the message etc.
This scales a lot better when I have a lot of pages simply fetching data for display, leading to a lot less boilerplate error handling needing to be implemented across multiple files. I could then have different "template" error boundary components for different cases as well.

page.tsx

async function getData(): Promise<{ data: SomeData | null }> {
  // In a dream world I could trycatch here and re-throw the error with custom data too
  const apiClient = new ApiClient();
  const data = await apiClient.fetchSomeData({});
  return { data };
}

export default async function Page() {
  const { data } = await getData();

  return (
    <DataDisplay data={data} />
  );
}

... Then an error boundary handling the display of the eventual error.

Again – I am open to misunderstanding the reasoning behind obfuscation, but in that case I would like to know in a bit more detail why I can't have control over the behaviour.

[RNm-dove]

I aggree with @tocaherge. If error.tsx can handle error message, we can write a fetch logic more simply.

When error.tsx cannot handle error message:

export default async function Page() {
  const { data: data1, error: error1 } = await getData1();

  if(!data1) {
    return <ErrorDisplay error={error1} />;
  }

  const { data: data2, error: error2 } = await getData2(data1);

  if(!data2) {
    return <ErrorDisplay error={error2} />;
  }

  const { data: data3, error: error3 } = await getData3(data2);

  if(!data3) {
    return <ErrorDisplay error={error3} />;
  }

  return (
    <DataDisplay data={data3} />
  );
}

When error.tsx can handle error message:

export default async function Page() {
  const { data: data1 } = await getData1();
  const { data: data2 } = await getData2(data1);
  const { data: data3 } = await getData3(data2);

  return (
    <DataDisplay data={data3} />
  );
}

[RNm-dove]

I came up with a workaround.

I created a wrap function renderAsyncOrError.

export function renderAsyncOrError(
  rendering: () => Promise<JSX.Element>,
): Promise<JSX.Element> {
  return rendering().catch((error) => {
    if (error instanceof APIError) { // catch your custom error
      return (
        <div>
          <h3>Something went wrong!</h3>
          <div>{error.message}</div>
        </div>
      );
    }

    throw error;
  });
}

And, used it every page.tsx and layout.tsx.

export default async function Page() {
  return renderAsyncOrError(() => {
    const { data: data1 } = await getData1();
    const { data: data2 } = await getData2(data1);
    const { data: data3 } = await getData3(data2);
  
    return (
      <DataDisplay data={data3} />
    );
  });
}

You can handle custom error.

[leerob]

Thank you all for the feedback in this discussion. I've updated the error handling docs to hopefully make this more clear.

https://rc.nextjs.org/docs/app/building-your-application/routing/error-handling

[Julien-Ose]

Thanks @leerob for your help.
I was really seduced by the possibilities Error boundaries seemed to offer. Is dealing with crafted errors in a similar way than uncaught ones a part of the upcoming works on Nextjs ?

[sorenhoyer]

@leerob I agree about handling known errors without throwing exceptions, but how on earth do you change the status code of your page without throwing an exception? You can't simply show a PDP page with an error and a status code of 200.

I use neverthrow to get rid of exceptions early in my code, but in the server component, even if I'm not using exceptions, in my switch statement I still have to call notFound() to trigger the 404 status code if the error is a ProductNotFoundError.

And the problems don't stop there, if I can't use the error.tsx and not-found.tsx. If I wrap an Error boundary around the server component, then whatever is thrown will be caught by that error boundary. But since I can't access the error at all, not even the status code, from inside the boundary component, then I'm unable to show either the NotFound view or the Error view.

So I think the documentation needs to also address this issue, so even for known errors, you should still be able to set the status code.

[Julien-Ose]

Based on @RNm-dove proposal (many thanks), I worked it in a similar way as follow :

import React from 'react';
import { ErrorContent } from '@/app/components/atomic';
import { ErrorPageWrapper } from './page-wrapper';
import { notFound } from 'next/navigation';

export const serverComponentErrorBoundary = async (
  fn: () => Promise<JSX.Element>
) => {
  try {
    return await fn();
  } catch (error) {
    if (error instanceof Error) {
      if (error.message.includes('404')) return notFound();
      return <ErrorContent error={error} />;
    }
    throw error;
  }
};

I use it as follow :

export default async function Page({
  searchParams,
}: {
  searchParams: SearchParams;
}) {
  // Preliminary operations, independent from data fetching

  return serverComponentErrorBoundary(async () => {
    const data1= await getData1();
    const data2= await getData2();
    const data3= await getData3();

    return (
        <PageComponent
          {...{
            seachParams,
            data1,
            data2,
            data3,
          }}
        />
    );
  });
}

Each case (weather it is a whole page, a nested page or a component) is quite particular, so the UI chunk fallback has to be adapted for each case.
So the approach is kind of heavy but works perfectly... until NextJS team proposes us something else someday.

Huge thanks to you all.