Avoiding Hidden Pitfalls in Sitecore Upgrades
Migrations and upgrading platform versions can introduce risks that may break functionalities. With Sitecore continuously releasing updates and enhancements, we aim to take full advantage of these opportunities to improve our clients' websites.
Recently, we encountered an unusual bug during development—one that is easy to overlook but can be difficult to debug and resolve if you haven’t encountered it before. This issue affects a critical aspect of our sites, and missing it can lead to unexpected bugs.
Missing Sites in the Dashboard and its Impact on Configuration
This issue occurred in our deployed environment, where none of the sites were visible on the dashboard. As a result, we were unable to configure essential settings that are only accessible through this interface. This limitation not only disrupted our workflow but also made it challenging to implement necessary adjustments for our sites. As shown in the screenshot below, the Site Collection appears empty, and an error code 500 is displayed, indicating configuration issues.
Sitemap Inaccessibility and its Impact on SEO and Integrations
Another noticeable issue is the inability to access the Sitemap page of your site. This can have a significant impact on search engine optimization (SEO) and site visibility, as crawlers rely on the sitemap.xml file to index your pages efficiently. Additionally, other third-party tools that depend on the sitemap for content discovery and updates may also be affected, potentially leading to missed pages in search results or broken integrations.
Solving these Critical Bugs
If you're encountering any of the errors above, don’t worry—the solution is simple. However, its simplicity can make it difficult to diagnose without knowing the root cause. To resolve this issue, we'll make all the necessary changes within the Content Editor.
Checking Your Sites in the Content Editor
Start by opening the Content Editor and navigating to each of your sites. Under the Settings item, you should see a Sitemap item. If it's missing, that's the source of the issue.
For projects with multiple Headless Sites, ensure that each site has its own Sitemap item. If only one site has it, that site will generate a sitemap page, but your Site Collection in the XM Cloud Dashboard will still appear broken.
If the Sitemap item is missing, don’t worry—I’ll guide you through fixing it.
What to do if You're Missing the Sitemap Item
No need to worry—the solution is simple. You just need to create the missing item. Sitecore ensures that the default values for this item are sufficient for the sitemap to function properly. Use the item path below to insert it correctly, as this is the standard template used in most projects:
/sitecore/templates/Foundation/JSS Experience Accelerator/SiteMetadata/Sitemap Settings
Steps to Add the Sitemap Item
- Right-click on Settings and select Insert from Template.
- The screenshot below shows what this should look like:
- In the popup, navigate to Templates, where you'll find Sitemap Settings.
- The screenshot below highlights its location:
- Name the item "Sitemap" (this is the expected name). While I haven't tested using a different name, you’re welcome to experiment if you're curious.
Publishing the Sitemap Item
To ensure the item is reflected on the frontend and the Sitemap page appears, publish the Sitemap item:
- Click the PUBLISH tab at the top.
- Select Publish Item (make sure the Sitemap item is selected first).
The screenshot below demonstrates this process:
Double-Check that the Issue is Resolved
To confirm that the issue is fixed, follow these steps:
-
Access the sitemap page by navigating to:
<DOMAIN_URL>/sitemap.xmlFor example, https://www.google.com/sitemap.xml.
-
Verify your XM Cloud Dashboard to ensure it's functioning as expected. Your Site Collection should display correctly, without error 500.
Below is a sample screenshot of what it should look like when everything is working properly.
What to do if the Problem Persists
If this solution doesn’t resolve your issue, don’t worry—there’s still a way forward. We successfully resolved this with the help of Sitecore Support, and I recommend reaching out to them for further assistance.
How to Contact Sitecore Support Effectively
To ensure a smooth resolution process, provide clear and detailed information about your issue. Here’s what you should include in your support request:
- A clear description of the problem – Explain what’s happening, what you’ve tried, and any patterns you’ve noticed.
- Screenshots – Highlight any error messages, missing items, or unexpected behavior.
- Video recordings (if possible) – Sometimes, a short recording of the issue can help Sitecore Support diagnose it more quickly.
Sitecore Support is responsive and will communicate with you in a timely manner to help resolve the issue.
