How to diagnose Umbraco upgrade problems
First of all: we test upgrading for every Umbraco version we release. We upgrade the solution we use for masterclasses, we upgrade Our Umbraco and when there's big changes we upgrade a bunch of other random sites too. So when it doesn't work for you, it's most likely that something went wrong on your computer, not in our upgrader. I'm not blaming the "victim" here, but just want to make you aware that we do all we can to make your upgrades succeed the first time. We miss stuff sometimes though, and that sucks, in which case we either try to correct that quickly or at least document it.
We also document how to upgrade your site as comprehensively as possible, so make sure to read the documentation, loads of hints and tips that we keep up to date:
Needless to say: you have your code checked into source control (or at the very least backed up before you upgrade) and you've made a full database backup before upgrading your site, right?
Troubleshooting
With that out of the way: shit happens! So let's try to figure it out.
I like to think of the Umbraco ZIP downloads as the "known good" state; when you have "problem x" after upgrading and installing a clean Umbraco install does not have "problem x" then something most likely went wrong with your upgrade.
Most people these days use NuGet for installing and upgrading Umbraco, that's also where most people have problems as it LOOKS like everything is done automatically for you, but sometimes it hasn't worked. NuGet can have a temperament where it "forgets" to do config transforms, runs into problems while doing the upgrade or "forgets" to copy certain files.
Time to debug! Let's start with the 3 C's: configs, cache and cookies.
Configs
Check that your config files in the ~/Config folder have been updated, and especially check if both your web.config files (the one in the root of your site and the on in the ~/Views folder) have been updated. How? Aha! Here is the best tip I will give you in this blog post: download a copy of BeyondCompare and import these settings. Finally, make sure to click the "Ignore unimportant differences" button, which hides unimportant whitespace differences.
Right, with a beautiful BeyondCompare install in place, download the zip file corresponding to the Umbraco version you're trying to upgrade to. Right click the zip file and choose "Select left folder for compare", then find the folder where your Umbraco install lives, right click it and choose "Compare to UmbracoCms.x.y.z.zip". You'll get a nice overview of folders and some will disappear as they're the same on both sides, leaving you with just the differences.
The first thing I usually check is the root web.config to make sure that everything that might be new in the Umbraco default web.config file is in the web.config file in my site. A special section to pay attention to is the runtime/assemblyBinding one that really needs the bindingRedirect versions to be correct.
After you've updated config files: try again, your site probably works just fine now.
Extra tip: while you're comparing it's also a great moment to check that all the required files are in your bin folder, we ship with what's needed in the zip file so make sure that all the files on the left side are also on the right side and that the versions are the same. Again, BeyondCompare only shows you the differences between the two folders so it should be easy to spot if anything is amiss.
Note: Yes, I know this is possible with WinMerge and other compare tools as well, but BeyondCompare is so much better than all of the others.
Cache
No? Okay then, try clearing your browser cache. Umbraco uses a lot javascript/angular/html that changes for most releases. The first thing to check: ~/Config/ClientDependency.config. Change the version number in that file (just make it 1 higher or lower) and try again. This should clear client side cache for most browsers.
However.. Chrome in particular is super aggressive in caching so it might not make a difference. So, for another hot tip in this post: if you use Chrome, hit the F12 button and the reload button next to the address bar is a little bit magical now. Try right-clicking on it...
You now have options! The best one of which is: Empty Cache and Hard Reload. It does what it says on the tin and requests all assets completely freshly and should load whatever is updated in Umbraco.
Cookies
We recently had a problem where an old cookie would throw a spanner in the works. Again, the developer tools in your browser can come to the rescue, I have the most experience with Chrome so again, hit the F12 button and go to the resources tab to find and delete all cookies.
Other problems
Check your log files, in ~/App_Data/Logs/ - whenever there's any kind of error that we can log, it will be in here. Look for things that look suspicious in the last few minutes that you were working on your upgrade and then do the simplest thing possible: copy an error and paste it into Google. You won't believe what happens next! (sorry.. I'm so sorry..).
Over the years Umbraco has had some let's say "interesting" database upgrades. Since v6 we have made this much more consistent and when the Umbraco upgrade installer runs we try to anticipate all the exotic database schema variations we had in the past and make everything consistent again. If you see database errors during an upgrade, it's likely that you're not the first person to see it, google it and see if there's manual workarounds. We try to pick up all of these errors and fix them in the next version so they don't pop up any more.
We sometimes break things, when it's on purpose we list them as being breaking changes on the release page of the version you're trying to upgrade to, if there's multiple versions between your current version and the version you're upgrading to, you might have to read up on all of the release pages to see if anything broke due to a change we made. So say you're upgrading from 7.3.6 to 7.4.1, make sure to read the release notes of 7.3.7, 7.3.8, 7.4.0.
But why?!
Yes, we do hear you cry "why can't it just work?!". Well, mostly: people do wildly different things with Umbraco. We learn every day and when we learn about something new and unexpected, we update the upgrade installer. This is an ongoing process that will never be perfect but it so much better than it was a few years ago. The NuGet experience these days is almost seamless and I encourage everyone with a new project to start out with a NuGet install and stick with it (even though it has grumpy days sometimes). It's well worth investing time in learning how NuGet works and what it does.
Automatic upgrades
Oh, and one more thing, on Umbraco as a Service, you get automatic upgrades. So you don't have to worry about any of this. You just wake up one day and see a message in the portal and continue making great sites for your clients.
