Unsuspected Error Handling: Solving Sitecore Puzzles
Being a Sitecore developer sometimes means that you are faced with errors that at first glance are both vague and puzzling. Most of the errors can be solved by using previous experience, common sense, a simple Google search for an article or quick chat with a colleague. But other times, there are errors that require deep investigation and nontraditional ways of troubleshooting. I came across two errors that occurred within the last month that, though unrelated, are both puzzling and required more investigation. I put together this blog post in order to reduce your need for deep investigation and just make the solution a simple Google search away.
Error: Placeholder ID
So let’s begin with the first puzzling error that I encountered. I was working in my local environment trying to access a Sitecore content page item in Content Editor when I was faced with a vague error message. As you can see in the image below, the message doesn’t offer a lot to go on.
Not all items with the same template were affected. By clicking on the Details, I could see that the first line said the Building Placeholder method had failed.
I checked the deployment server and found no issues with problematic items that existed in my local environment. Two different environments had the same code base but were acting differently.
Content changes and erasing the entire structure in my local environment didn’t help. Further analysis took me to the point where I was looking at config changes in both environments. One of my colleagues (Yury Fedarovich) suggested that I should check the renderings field in the layout section of an item. Items which were showing up without errors on remote server looked unsuspicious. So how could I have this issue in my local environment?
In order to look at the item and renderings layout field in my local environment that had the placeholder ID error, I used the Sitecore admin tool called ‘DB browser.’ Sitecore installation comes with DB browser (url: YOUR_SC_INSTANCE/sitecore/admin/dbbrowser.aspx), which helps with accessing items in a much quicker way than the Sitecore GUI does. It gives you the raw view of all the fields within an item that are stored in the SQL database.
I copied the renderings field with the error and formatted it in Visual Studio. This is where I noticed that the rendering and its placeholder was missing a datasource ID and no placeholder path was defined. Sitecore was not able to resolve the ID highlighted in the red rectangle below.
Short description of Renderings namespaces:
r – rendering field definition
d – device (default)
r uid – auto-generated rendering ID
p – pointer to the auto-generated rendering ID
s:ds – datasource ID
s:id – source rendering ID
s:ph – placeholder path (dynamic or regular)
So what caused this error to occur?
After examining all the IDs in the renderings layout field, I noticed that one of the placeholder definitions was missing appropriate syntax (see highlighted red rectangle, shown above). The next obvious step was to look at standard values of the page template items. The difference between my local and items deployed on the server was hidden in ‘Final renderings.’ Since BrainJocks’ practice is to do all our development work in the ‘Shared’ renderings domain, someone must have accidentally changed it and added additional renderings directly on the server in ‘Final’ rendering mode.
Final renderings layout combines shared and versioned presentation details; therefore, even if we had correct and synced Shared details among all environments, ‘Final’ contained the definition for the missing rendering placeholder (ID). That was the reason why page items didn’t throw the unpleasant ‘placeholder ID’ error in Content Editor.
One important thing to mention here is that the deployment process didn’t update the ‘_Standard Values’ rendering field correctly. Having templates’ ‘Standard Values’ items out-of-sync created a side effect and masked the problem that would surely show up in new environment.
Using DB Browser and navigating to affected items, I was able to remove parts of the Renderings field that contained rendering placeholders without a source.
Also, syncing and removing the ‘Final’ Renderings definition on the server matched Page Templates ‘_Standard Values’ with our source control.
Error: Missing Images on Content Delivery Server
The second error occurred when the client noticed on their LIVE server that some images were not rendering correctly. Though they appeared fine when they were first uploaded, after a certain amount of time the images stopped showing up. I went to examine the path and HTML source for one of the images, but both looked fine. When trying to access the image, I got the error shown below.
IIS was trying to load images as ASP.NET MVC View (???). The actual resolved path of those image source URLs created a path that looked strange and not even close to the source from HTML or the browser URL request. It is important here to add this: Even the images with the exact same names, sizes and extensions as the ones that were already in Sitecore, which we tried to upload and put on the page, were failing.
If your issue is urgent, such as images appearing broken on the live site, you can use this short-term solution to mask the problem and use Item IDs for resolving media items:
<setting name="Media.UseItemPaths" value="false"/>
Although the short-term solution is a quick fix, it is not the final solution. Using IDs instead of Sitecore item names as a part of image path will look like this:
Possible Cause and Solution
The possible cause of the problem might be the “NOT_A_VALID_FILESYSTEM_PATH” file in the website root folder. It is created by IIS web server when the media extension is incorrect and both of the following conditions are true:
- The argument provided to the “Server.MapPath” method includes a character that can’t appear in a valid filename, such as colon (“:”) or question mark (“?”).
- The <httpRuntime> section of the web.config file includes the following attribute: relaxedUrlToFileSystemMapping=”true”
- Change the “relaxedUrlToFileSystemMapping” attribute value to “false”.
- Remove or rename the “NOT_A_VALID_FILESYSTEM_PATH” file.
- Make sure that all your recently uploaded media items have the correct value in the “Extension” field without special characters like “:”, “?”, “^”, etc.
Working with Sitecore is fun, interesting and we all can learn something new every day. If you ever come across the problems I’ve had in the past few weeks, I hope this post will guide you in the right direction. Happy Sitecoreing!