Our SXA Toolbox Disappeared, Now What?
We recently worked with a client whose solution was built on Sitecore XM 10.3.1 with SXA 10.3 and JSS 21.5.x. In our development phase we faced a weird issue where our SXA toolbox pulled a houdini on us. To save you the pain of troubleshooting and head scratching, find below what caused and how to work around it. Spoiler alert, this a bug in Sitecore which is registered with their support with reference number 611359.
The Cause of the Disappearing SXA Toolbox
Lets first understand how the toolbox gets loaded in the first place. If you open up your DevTools in your browser and filter the requests by Headless in your Network tab, you’ll see it has two requests, one for the JS file and another one for the CSS. The important one is the JS file here and below is the request for the file. If this file is not loaded, then your toolbox will not appear.
<instance name>/sitecore/shell/-/media/Base-Themes/Headless-Editing-Theme/Scripts/optimized-min.js?
Guess what, in our case the file wasn’t loading and we found the culprit was setting lowercaseUrls to true . This is a common setting that gets used in almost any project to have consistent URLs for your clients. So naturally we registered a ticket with Sitecore and this is where the fun starts.
Is There a Fix or a Workaround?
Before I go ahead and share our struggle, lets discuss the workaround quickly. As I said earlier, this is a bug in the Sitecore 10.3.1 version and that there is no fix available as of writing the blog. What we did was to apply role setting, so in the config where we had lowercaseUrls to ture we simply added role:require="ContentDelivery". However, there is a hot fix available if you’re on Sitecore 10.3 but please DO NOT install this on 10.3.1 as it’ll break your Experience Editor altogether even though we were suggested to install.
The Struggle in Fixing the Issue
The disappearance was first noticed by our QA team at the end of one of our sprint cycle and by this time we had already made almost a dozen PRs. We initially went back to a commit from the previous sprint’s last PR to check and the toolbox was fine so we spent an entire day of going through the dozen PRs (so many up/down for docker) to find which PR made the toolbox disappeared and that’s where we found the lowercaseUrls settings being the culprit. At this stage we thought, ah its fine we lost a day only from our current sprint but oh boy we were so wrong.
From the day of registering a ticket with Sitecore, it took almost a month of back and forth with them which ended up finally with them acknowledging this is a bug in their current version. We spent around 3-4 days over a period of month to get to this part. Sitecore confirmed that the script name was hardcoded with such string ("/Headless-Editing-Theme/"), which will not work well when lowercaseUrls setting is set to true. And so they provided the below two hotfixes, initially they gave the cumulative one which contains fixes for other issues too and then another one which was specific to this problem.
We installed both the hotfixes that were provided to us, both of which ended up breaking our Sitecore instances and we had to restore from our backups. The fixes will work if you’re on 10.3 so please be careful when you install them.
That’s it folks! We went through the pain of troubleshooting so you don’t have to. If you’ve upgraded your JSS version to 21.6.x and are facing an issue with your front-end not loading, checkout our blog for a fix on it.
Meet Karan Patel
Sitecore Developer
🚀🎸🎮
Karan is a Sitecore Certified Developer with over 2 years of experience building and implementing Sitecore solutions using ASP .NET MVC, React, Azure and AWS. He's an avid fan of Counter-Strike and can usually be found playing it if he is not developing. In his spare time, he likes to play guitar and cook Indian food.