In this tutorial, you will learn some practical troubleshooting tips that should help you diagnose why your Episerver start page fails to load. I have been encountering this error a lot recently. On a recent project, we had a requirement to tear up/down the Episerver CMS database fairly frequently. Normally I would automate this process as part of the Ci/Cd pipeline. In this scenario, I took on a legacy project that had very tight timescales. There was not enough time before launch to fix the Ci/Cd pipeline. This meant there were lots of manual clean and restores using SSMS on a nearly daily basis. As with any manual deployment process, mistakes creep in etc.. and errors occurred. By far the most common issue I encountered during this period was the start page not loading. So I have created a guide to help you out.
FYI if you want a tool to help you manually tear up and own an Episerver database, I've even written a little app that will do most of the hard work for you, available here 🔥🔥🔥
Document All Your Deployment Processes
Before I kick off with the code, first I'd recommend that you write a step-by-step guide of every task that you need to follow in order to deploy your website, re-populate it with data, etc... If you haven't read the Phoenix project I suggest you do. In the book, there's a great and very easy to understand explanation about why getting visibility on processes will help you save time and debug things more efficiently. In essence, it boils down to these two factors:
It allows other developers to replicate the tasks with fewer errors
It gives the business greater visibility as to where your time is going and gives you better justifications for spending time automating things.
In my situation, the deployment process involves 16 steps and if not followed correctly then the blank start page error would happen. This is why I recommend documenting your process, as when you fix this error, you can prevent other developers from making the same mistakes. Assuming you have done that, let us look at some of the causes for a blank start page.
The file '/link/43F936C99B234EA397B261C538AD07C9.aspx' does not exist.
For people using Episerver for a while, you might think that the error is caused due to a missing media file in the blog storage, however, it isn't. This error means that Episerver can't find a start page. If you see this, go to your site definition section and ensure that the start page is set. Set it and save it, this usually resolves this issue.
I Get A 503 Sevice Unavailable Error When My Episerver Start Page Loads
A 500 error is usually caused by a bad configuration somewhere. If this happens when your start page loads, nothing will be logged within the Episerver logs. Instead, 500 logs can usually be found in the Windows application logs. 90% of the time these errors mean there's something wrong with your
web.config. 500 errors are common the first time that you try to install an Episerver website on a new server. If this is happening on your site, I recommend reading, Getting A 503 Sevice Unavailable Error When My Episerver Start Page Loads
Site Definition Relate Errors
This is usually down to the site definition file not being set up correctly, or, in a multi-language website, the default culture has not been set. To fix this, open up your websites site definition section within the Episerver admin UI:
Ensure that the hostname you are using to access your Episerver website is mapped in the site definitions AND the correct language has been set (if applicable)
BONUS TIP: If your site settings look ok, but still don't work, delete and re-create the site definition. On a recent project, the website's site definitions were created in code (see here to do that. It looked correct, however, deleting the site definition and re-creatin git manually made the site work again.
If you're reading this and your page still isn't loading, the issue is likely a code based issue. Tracking down code errors will be very specific to your application, however, there are some good steps to follow:
Can you access a static HTML file in your web root via a browser? If not it's an environmental issue
Can you access another Episerver page, e.g. the search page, it could be your homepage template has an issue
Has the Windows event log logged anything?
Has the Episerver logs logged anything useful?
Remove features from the homepages view file, one section at a time
App\_datadirectory pointing to a valid location?
Does the Chrome console tab show any errors
Does the Chrome network tab show any errors?
Do you have a valid Episerver license? This won't break a page but can break JS on the page
Following all these tips should hopefully have gotten your start page working again. Getting the start page to work can be very frustrating. In most instances, it will be something small and annoying. Keep at it and I'm sure you will figure it out in no time. Happy Coding 🤘