Sitecore XM Cloud Pages Suddenly Stopped Rendering the Site When Connected to a Local CM

The Importance of Up-to-Date Solution Images in Sitecore XM Cloud

I recently realized the importance of keeping my solution images up to date with the latest Sitecore XM Cloud base images. It all started when developers on my team started to report that XM Cloud Pages stopped rendering their local CM page items.

This Article is Relevant if

1. You develop a Sitecore XM Cloud solution locally using Docker containers.
2. You ran the .\up.ps1 script once, a while ago, when setting up your development environment.
3. Since that time, you only run docker compose down and docker compose up -d to manage your Docker containers.
4. You connect Sitecore XM Cloud Pages to your local containers using the local storage key or the Sitecore XM Cloud Extensions browser add-on.

The Symptoms

Sitecore XM Cloud Pages stopped loading our pages in the central panel. It was blank. In addition, it was displaying an error message saying:

The item you requested cannot be displayed. Either the item does not exist or you do not have permission to view it.

The Investigation

For this specific issue, in the browser network tab, I found 2 POST calls to https://xmcloudcm.localhost/sitecore/api/ssc/horizon/query/?sc_horizon=api&sc_headless_mode=api that returned a 200 OK status but contained errors in the response:

1. The first call was to get the list of components the author can add to the page ("operationName": "getComponents"). It returned this error:

    "Cannot query field \"componentName\" on type \"ComponentInfo\"."
   

2. The second call was to get the item type ("operationName": "GetItemType"). It returned this error:

    "Cannot query field \"baseTemplateIds\" on type \"Template\"."
   

Realities of Working With a SaaS Product

Sitecore XM Cloud and XM Cloud Pages are SaaS products that are in constant evolution. New features are released every week. Some of the new features require matching services, APIs, endpoints, GraphQL schemas, etc. on the CM instance, or on the website front-end.

In this case, our local CM instances were missing important GraphQL schemas that were now required by Sitecore XM Cloud Pages to work as expected.

One could argue that this is a breaking change. Sitecore should allow developers working on any version of the CM base Docker image to use the Pages editor. This is part true. Sitecore manages your XM Cloud environments and sometimes redeploys them using their latest base images. This happens when they issue important hotfixes or when they update their base images with new Microsoft base images that contain Windows hotfixes. Thus your hosted environments are almost always up to date with the latest XM Cloud base Docker images.

This is not the case for our local development environments. If you are running locally using base Docker images that are too old, you might not have the services, APIs, endpoints, or GraphQL schemas that XM Cloud SaaS applications like Pages require for those new features.

Keep Your Local Environment Up to Date

The solution is to update your XM Cloud Docker base images, rebuild your solution Docker images on top of these latest base images, and restart your containers. This is all accomplished by the known .\up.ps1 script. However, this script also pushes your serialized items to the Sitecore master database and you could lose precious changes you have not yet pulled.

To make sure not to lose any item change and fix the issue:

1. Check whether you have item changes to pull by running dotnet sitecore ser pull -w
2. If you have item changes to pull:
   1. Pull item changes by running dotnet sitecore ser pull
   2. Commit them.
3. Run .\up.ps1 to update the XM Cloud base Docker images, rebuild your solution Docker images on top of these latest base images, restart the containers using your new solution Docker images, and push serialized items to the master database.
4. Reload XM Cloud Pages and it should now work as expected, displaying your local pages.

Happy Sitecoring!

---