Apr 15, 2024Sitecore XM CloudNext.jsPlatform Engineering

How to Create Custom Error Pages in Sitecore XM Cloud

Ideally, users should never hit an error page, but production sites always have edge cases. A clear 404 or 500 page helps people recover quickly and continue their journey.

If you are using Sitecore XM Cloud with Next.js and Vercel, Sitecore already supports custom error pages. The common setup is straightforward until your shared components (like header or footer) depend on external data.

Configure Error Pages in Sitecore

Create your custom pages in the Pages Routing folder and map them in your tenant settings.

Sitecore settings showing custom error page mapping

When the layout service returns a 404 or 500, the app routes to src/pages/404.tsx or src/pages/500.tsx.

The External Data Problem

The default GraphQL error page query returns layout data, but it does not include external data your components may need. That can leave sections of the error page blank even though the route itself resolves.

In my case, the fix was to align 404 behavior with the dynamic route flow and ensure component registration plus component props were handled before returning the final page payload.

Implementation Pattern

Use GraphQLErrorPagesService to fetch the error page metadata, then build params for the route path so your page props factory can resolve component data consistently.

export const getStaticProps: GetStaticProps = async (context) => {
  const resultErrorPages = await errorPagesService.fetchErrorPages();

  const paths = [
    `_site_${site.name}`,
    ...(resultErrorPages?.notFoundPagePath?.split("/")?.filter((x) => x.length > 0) ?? []),
  ];

  context.params = { path: paths };
  const props = await sitecorePagePropsFactory.create(context);

  return {
    props: {
      componentProps: props.componentProps,
      layoutData: resultErrorPages?.notFoundPage?.rendered || null,
      headLinks: [],
    },
  };
};

One Important Caveat

Do not include spaces in the Sitecore item names used for error page routing. There is a GraphQL-side issue that can break the query when spaces are present.

Final Result

With this approach, custom error pages can render the same component ecosystem as the rest of your site, including components that require external data. Users get a useful page instead of a partially rendered fallback.

References

This post was originally posted at: https://www.velir.com/ideas/how-to-create-custom-error-pages-in-sitecore-xm-cloud

Share this post