Troubleshooting the Next.js Multisite add-on

Version: 22.x

This topic describes common issues with the Next.js Multisite add-on and explains possible solutions.

Debug the site resolution

If the resolved site for a given domain is not as expected, you can troubleshoot with the help of JSS debugging tools.

To enable debugging for the Multisite add-on:

  1. Turn on debug logging for multisite by enabling the sitecore-jss:multisite namespace.

  2. If necessary, increase the debug depth using the DEBUG_DEPTH environment variable.

With debug logging enabled, you can see the site information fetched from Sitecore during the app bootstrap phase. The SiteResolver uses this information to determine the site based on the hostname.

You can also see MultisiteMiddleware debug trace logging that shows detailed information for each request, including the resolved site name.

Resolve CORS errors for Next.js assets (for hosting services other than Vercel)

When using hosting services other than Vercel, you might experience Cross-Origin Resource Sharing (CORS) errors for Next.js asset requests (<mysite>/_next/static/<path>).

To resolve CORS errors for Next.js assets:

  1. Check that you have set the PUBLIC_URL environment variable. This variable is required for integration with Sitecore editors (without it, relative Next.js asset requests fail in Pages/Experience Editor).

  2. Ensure all domains used in your multisite configuration have access to the domain used for the PUBLIC_URL variable, for example, by using the Access-Control-Allow-Origin header.

Note

This issue does not affect applications deployed on Vercel because Vercel deployments use the VERCEL_URL environment variable as the public URL. The VERCEL_URL is generated on deployment, and all origins can access it.

Resolve CORS issues caused by missing host domain name

Cross-Origin Resource Sharing (CORS) errors can occur on the CM host when the domain name is missing in the CORS header configuration. To mitigate this issue, we've provided the new cors-header.js plugin, which adds the sitecoreApiHost header when it is missing.

The plugin also lets you fix related CORS issues that might occur when trying to use different fonts from remote sources on SitecoreAI.

Resolve 401 unauthorized error when hosting your app on Vercel

Vercel enables Deployment Protection by default for new projects. If your SitecoreAI environment is not configured to work with Deployment Protection, your app might encounter a 401 unauthorized error when accessing static assets using the VERCEL_URL.

To resolve this error, set up your app to work with Deployment Protection or disable Deployment Protection.

Do you have some feedback for us?

If you have suggestions for improving this article,