Skip to main content

SitecoreAI Display Name URLs Returning 404 with Content SDK

I recently came across an interesting routing issue in SitecoreAI where enabling useDisplayName started generating much cleaner URLs, but those URLs were returning 404 in the rendering host.

The interesting part was that the same pages worked perfectly when accessed using their original item-name based URLs.

The Requirement

The team I was helping had category pages with URLs like:

https://testing.mysite.com/Products/1341592/1342427/1342434

These URLs are technically valid, but they aren't particularly user-friendly.

The preferred URL was something like:

https://testing.mysite.com/Products/category1 display name/category2 display name
/category3 display name

In Sitecore, this can be achieved by configuring the link provider to use the item's display name when generating URLs.

The Configuration Change

We deployed the following Sitecore configuration patch in the staging environment:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <linkManager defaultProvider="switchableLinkProvider">
      <providers>
        <add
          name="localizedProvider"
          patch:attribute="useDisplayName"
          useDisplayName="true" />
      </providers>
    </linkManager>
  </sitecore>
</configuration>

After deploying the patch, Sitecore started generating URLs using display names, for example:

https://staging.mysite.com/Products/category1 display name/category2 display name
/category3 display name

So far, everything looked correct.

The Problem

The problem appeared when opening the newly generated URL.

The display-name URL returned:

404

However, the same page could still be opened using its original item-name based URL.

/Products/1341592/1342427/1342434

This made the problem particularly interesting because Sitecore was able to generate the display-name URL, but the rendering host could not correctly resolve the same URL back to the Sitecore item.

Environment Comparison

There was also an interesting difference between the staging and testing environments.

In staging, the useDisplayName configuration had been deployed.

In testing, it had not.

The behavior looked like this:

Environment Item Name URL Display Name URL
Testing Works Works
Staging Works 404

This initially made the configuration patch look like the obvious cause.

Content SDK vs JSS SDK

One important detail in this investigation was that the rendering host was using the Sitecore Content SDK, not the JSS SDK.

This became important because some of the Sitecore documentation around display-name routing specifically discusses JSS Next.js applications and its routing behavior.

So it was necessary to distinguish between:

  • How Sitecore generates the URL
  • How the rendering host receives the URL
  • How the incoming URL is converted into a Sitecore route
  • How the route is ultimately resolved through Sitecore's APIs

Simply enabling useDisplayName="true" changes URL generation. It does not necessarily mean that every part of the rendering host's route-resolution process will automatically understand the new display-name based path.

The Investigation

We shared the behavior with Sitecore Support and provided examples of both working and failing routes.

One of the useful tests was to compare the GraphQL layout query using the two different route paths.

The display-name route was:

/Products/category1 display name/category2 display name
/category3 display name

while the original item-name route was:

/Products/1341592/1342427/1342434

The same test could then be performed using the different context IDs for Preview and Live.

This helped narrow the problem down to route resolution rather than the actual page content.

Sitecore Confirmed the Bug

After investigating the issue, Sitecore Support confirmed that the behavior was related to a known product issue.

The Sitecore bug reference is:

DP-2604

Sitecore described the issue as:

Layout query with name route path fails if page has display name.

Sitecore also confirmed that their developer team was working on a fix.

The Workaround

In our case, the practical workaround was to avoid relying on the display name for the category path.

We updated the implementation so that categories were created using their name rather than the category ID, and we removed the display-name configuration.

This allowed the URLs to remain readable without depending on the problematic display-name route resolution.

The workaround was confirmed to be effective, and Sitecore Support advised continuing to track the issue using the bug reference DP-2604.

What I Learned From This

This was a good reminder that URL generation and URL resolution are two different parts of the problem.

It is possible for Sitecore to generate a perfectly valid-looking URL while the rendering host or downstream API cannot resolve that URL back to the correct item.

When introducing display-name based URLs, I would therefore test both sides:

  1. Is Sitecore generating the expected URL?
  2. Can the rendering host resolve that URL?
  3. Does the corresponding Layout API or GraphQL query resolve the route?
  4. Does the behavior differ between Preview and Live context?
  5. Does the same route work when the display-name configuration is removed?

In this case, the issue turned out not to be an application implementation problem but a Sitecore product bug.

Conclusion

If you are using SitecoreAI and enable useDisplayName, but your newly generated display-name URLs return 404 while the original item-name URLs continue to work, it is worth checking whether you are hitting the same issue.

The relevant Sitecore bug reference is:

DP-2604

The workaround in our case was to use category names rather than category IDs and remove the display-name configuration until the underlying issue is resolved.

This is one of those Sitecore issues where the symptom initially looks like a rendering-host routing problem, but the actual problem can be deeper in the route resolution performed by the Sitecore platform.

Hopefully this saves someone else a few hours of debugging.

Labels:

Comments

Post a Comment

POPULAR POSTS

Sitecore PowerShell Script to create all language versions for an item from en version

  We have lots of media items and our business wants to copy the data from en version of media item to all other language versions defined in System/Languages. This ensures that media is available in all the languages. So, we created the below powershell script to achieve the same -  #Get all language versions defined in System/Languages $languages = Get-ChildItem /sitecore/System/Languages -recurse | Select $_.name | Where-Object {$_.name -ne "en"} | Select Name #Ensuring correct items are updated by comparing the template ID  $items = Get-ChildItem -Path "/sitecore/media library/MyProjects" -Recurse | Where-Object {'<media item template id>' -contains $_.TemplateID} #Bulk update context to improve performance New-UsingBlock (New-Object Sitecore.Data.BulkUpdateContext) { foreach($item in $items){    foreach($language in $languages){ $languageVersion = Get-Item -Path $item.Paths.Path -Language $language.Name #Check if language versi...
Post a Comment
Read more

Export Sitecore media library files to zip using SPE

If you ever require to export Sitecore media files to zip (may be to optimize them), SPE (Sitecore Powershell Extension) has probably the easiest way to do this for you. It's as easy as the below 3 steps -  1. Right click on your folder (icons folder in snap)>Click on Scripts> Click on Download 2. SPE will start zipping all the media files placed within this folder. 3. Once zipping is done, you will see the Download option in the next screen. Click Download Zip containing the media files within is available on your local machine. You can play around with the images now. Hope this helps!! Like and Share ;)
Post a Comment
Read more

Make Sitecore instance faster using Roslyn Compiler

When we install the Sitecore instance on local, the first load is slow. After each code deploy also, it takes a while for the Sitecore instance to load and experience editor to come up. For us, the load time for Sitecore instance on local machines was around 4 minutes. We started looking for ways to minimize it and found that if we update our Web.config to use Roslyn compiler and include the relevant Nugets into the project, our load times will improve. We followed the simple steps - Go to the Project you wish to add the NuGet package and right click the project and click 'Manage NuGet Packages'. Make sure your 'Package Source' is set to nuget.org and go to the 'Browse' Tab and search Microsoft.CodeDom.Providers.DotNetCompilerPlatform. Install whichever version you desire, make sure you note which version you installed. You can learn more about it  here . After installation, deploy your project, make sure the Microsoft.CodeDom.Providers.DotNetCompilerPlatform.d...
1 comment
Read more

Experience of a first time Sitecore MVP

The Journey I have been working in Sitecore for almost 10 years now. When I was a beginner in Sitecore, I was highly impressed by the incredible community support. In fact, my initial Sitecore learning path was entirely based on community written blogs on Sitecore. During a discussion with my then technology lead Neeraj Gulia , he proposed the idea that I should start giving back to developer community whenever I get chance. Just like I have been helped by many developers via online blogs, stackoverflow etc., I should also try to help others. Fast forward a few years and I met  Nehemiah Jeyakumar  (now an MVP). He had a big archive of his technical notes in the form Sitecore blogs. I realized my first blog dont have to be perfect and it can be as simple as notes to a specific problem for reference in future. That's when I probably created my first blog post on Sitecore. At that time, I didn't knew about the Sitecore MVP program. Over the years, I gained more confidence to writ...
2 comments
Read more

Clean Coding Principles in CSharp

A code shall be easy to read and understand. In this post, I am outlining basic principles  about clean coding after researching through expert recommended books, trainings and based on my experience. A common example to start with is a variable declaration like - int i  The above statement did not clarify the purpose of variable i. However,  the same variable can be declared as -  int pageNumber The moment we declared the variable as int pageNumber, our brain realized that the variable is going to store the value for number of pages. We have set the context in our brain now and it is ready to understand what the code is going to do next with these page numbers. This is one of the basic advantages of clean coding. Reasons for clean coding -  • Reading clean code is easier - Every code is revisited after certain amount of time either by the same or different developer who created it. In both the cases, if the code is unclean, its difficult to understand and u...
Post a Comment
Read more