Common Sitecore XM Cloud and Next.js Routing Issues and How to Resolve Them
Sitecore’s default setup uses the Pages router from Next.js. This setup has many dependencies and a lot of configuration to get right, before it will work for you. This article lays out examples and areas which could go wrong to save you time and frustration to get it working. Or worse, to fix it after something unknown has gone wrong. Don’t hunt for needles in a haystack, get a look at the likely issues first!
Couldn’t Find the Right Article?
This article is not about making custom 404 pages for your Sitecore site! I saw a lot of search results for that on similar search terms, in case you ended up there. If you were suffering the same thing I was and couldn’t find a troubleshooting guide for your actual routing problem between all the custom error page setup, well, you’re in the right place now. This article is strictly about fixing your Next.js routing problems, which usually show up as 404 errors.
Routing Setup Example
Sitecore’s Default Setup
The first thing to check is whether someone has changed the default Sitecore setup. Maybe they were making a custom route and renamed the wrong file. Maybe you had a merge conflict resolve badly. Maybe a file got corrupted during a Windows update. Maybe you started from scratch and don’t have it at all, but here it is for comparison purposes.
You should see this in your “src” folder:
[[...path]]].tsx is the main, catch all route file.
Make sure this file has not be renamed. All of the special characters are vital, too.
Was the Sitecore Site Name Changed?
Check both your local env files, and your site setup content in the Sitecore XM Cloud CM editor. Is there a name mismatch? You can find the site name setting in the path like:
/sitecore/content/MyTenant/MySite/Settings/Site Grouping/MySite
It’s worth checking if there’s a different env file than you expect, too. Sitecore loads the env files in this order:
scjssconfig.json..env..env.local(for local environments only).
Note that if you are testing a change to the site name, your env file changes may not have been reflected in the running app yet, too. If both the file and the item match, and you’ve just made changes, restart the app and it should work then.
Custom Routing Location
If you are making a custom route, it should look like the Sitecore default route. Make sure there is a folder under ‘src/pages’ that matches your route name, and then a [[…path.tsx]] file too. Make sure the tsx file is working and returns something reasonable, too. Your error catching code might be throwing NotFound, too. Alternatively, someone might have been testing a custom error page.
In both cases, check your path.tsx file, and the original Sitecore path.tsx file, for code that looks like this:
if (notFound || !layoutData.sitecore.route) {
return <NotFound />;
}
if( debug === true) { return <NotFound />; }
Sometimes there is a NotFound variable in places you wouldn’t expect that is being accidentally called, or actual errors that cause it to be called. In this example, if the Sitecore data was missing, you’d see that too.
Checking the Layout Service
That first line in the code about layoutData.sitecore.route comes from the default Sitecore path.tsx file. This means problems in the layout service can cause you to see the not found page, on every page. If you are luckier, the problems might be limited to the page you are working on.
Try loading the layout service like this:
/sitecore/api/layout/render/jss?item=[path]&sc_lang=[language]&sc_apikey=[key]
Each of these gives you something to check, too. Make sure the api key was set correctly, that the language is available, and that the item is actually at the path it should be.
Make sure the JSS Editing secret is set and matches your site setup, too.
Check the rendering host items to make sure they have the right values that match your config setup too: They live in /sitecore/system/Settings/Services/Rendering Hosts if you are using Headless SXA.
Next.js Special Folder Handling:
We had one strange case, where a git merge clean resulted in an empty “pages” folder with another empty route folder inside it called “products”. Because pages is a special keyword for the Pages router in Next.js, this caused it to think that there were no routes set at all, since there were no tsx files to route to. Another important name is ‘app’. Next.js also has an app router to go along with the pages router. Don’t name folders with these names, and don’t nest them inside each other, either.
Check on your rendering host for folders with these names in case this happens to you; these empty folders may have ended up deployed to your local instance even if they are no longer in source control.
There’s a surprising number of moving parts that all have to work correctly to get pages to display for you! Hopefully this list of places to look helps you find whichever one is not working for you.
