Troubleshooting a Sitecore issue #1 – a step by step example

Recently a developer here at True Clarity asked me to help investigate a problem with the links database in Sitecore. It is becoming increasing more common for us to work on code we did not necessary write ourselves and investigate issues in Sitecore builds which are now a number of years old.

I thought I’d write a quick piece about how we tackled this particular issue. This might be fairly obvious to more experienced Sitecore developers but it may help some people who find it hard to know where to start when troubleshooting such issues.

Here's what I'll cover

  • Inspecting the code
  • Inspecting the database
  • Do your research
  • Make use of fresh Sitecore installs
  • Debugging sitecore libraries
  • Quick throwaway test pages

Inspecting the code

The problem we had was that a list of products were being rendered on the UI but were missing links to relevant information pages. The anchor tag just wasn’t being rendered to the page.

The first thing to discover was how these links were being rendered. A quick look with the debugger attached at the source code quickly gave the answer – the problem was that the link was referencing a referrer of each item. Referrers are kept in the links table yet each item had no entries in the database - Why was this?

Inspecting the database

The next port of call was the database itself to confirm the assumption – indeed the following query yielded no results.

SELECT * FROM Links Where TargetItemID = '{D5DF8477-8257-4207-817F-05EAC8E1B66B}'

So did the links database need a rebuild? – We could have done this but on a large database this is quite a time consuming operation – instead lets dig into one specific product item in Sitecore which is not updating its links correctly.

Do your research

Prior knowledge of the links database (or a quick Google search) tells us that links should be updated on save in which case we will have a row in the links database with the TargetDatabase as ‘master’ and on publish – in this case we would have another identical row but with the TargetDatabase ‘web’.

Make use of fresh Sitecore installs

I find it really useful to have a blank instance of Sitecore on my machine, I have one for a number of versions. A quick test on a blank instance of Sitecore found that this is indeed the case. On save we see a new row in the links database. On a side note fresh installs of Sitecore are really useful and can often quickly tell you if a problem is a code, config or database issue.

So knowing how Sitecore should work we knew there was a code/config issue somewhere. Taking a look at the troublesome item (our example product) something quickly grabbed our attention. There was only one field and the field in question, a treelist, was in fact a custom implementation of the treelist control. This was the likely culprit – but why wasn’t it generating links?

After inspecting the code for the custom control (which was fairly straightforward) there appeared no obvious reason. However after swapping the field type for a standard treelist we could confirm that it certainly was the custom control at fault. The standard treelist did indeed update the database on save with the correct links.

Debugging sitecore libraries

This is where I jumped directly to the answer – but if you don’t have a good knowledge of how custom field types in Sitecore work you may need to investigate further. If our custom control is not updating the links database one option is to dig into how Sitecore generates its referrer links. If you look at the sitecore config you will notice this code is fired on item:saved:

<handler type="Sitecore.Links.ItemEventHandler, Sitecore.Kernel" method="OnItemSaved" />

You can use Reflector / ILSpy to decompile Sitecore (or indeed any) libraries to see what the code should be doing - in this case how Sitecore was attmpting to get links for our field.

Quick throwaway test pages

Copying the decompiled code into an aspx page is a quick way of debugging such issues. We can quickly copy all relevant code from the sitecore assemblies into a new page with a <script runat=server><script/> in the markup (but no code behind to save on building the solution) and start debugging as follows:

private Sitecore.Data.Items.Item item;
    protected void Page_Load(object sender, EventArgs e)

        item = Sitecore.Data.Database.GetDatabase("master").GetItem(new ID(new Guid("{D5DF8477-8257-4207-817F-05EAC8E1B66B}")));

        var links = GetLinks(ItemLinkState.Any, false);

        foreach (var link in links)
        var linkedItem = Sitecore.Data.Database.GetDatabase("master").GetItem(link.TargetItemID);              
           Response.Write("Source Id:" + link.TargetItemID + " Name: " + linkedItem.Name + "<br/>");

    private ItemLink[] GetLinks(ItemLinkState linkState, bool allVersions)
       System.Collections.Generic.List<ItemLink> list = new List<ItemLink>();
        Sitecore.Data.Items.Item[] array;
        if (allVersions)
            array = this.item.Versions.GetVersions(true);

        [lots more code...]

If you were to debug this code which is copied directly from the Sitecore assemblies you would quickly see that the problem area is a piece of code returning an empty object during some reflection logic where sitecore is attempting to create an instance of the the custom field type.

It does this by looking for the field type in FieldTypes.config – and there was our problem – it was missing.

In this scenario you would probably jump to problem without needing to inspect Sitecores own code, but I included it just as an example of how far you can go if needs be to troubleshoot issues.

Dave Leigh

Web, and long time Sitecore developer based in Bristol, UK, working at Valtech - - @valtech.
I occasionally do other things too.