Umbraco 13 to 17: Why a Direct Upgrade Doesn't Always Mean a Simple Upgrade
In our recent article, "Umbraco 13 vs 17: Why Now Is the Time to Upgrade and How to Do It Right", we explored why organisations running Umbraco 13 should begin planning their move to Umbraco 17 sooner rather than later.
Since then, one question has come up repeatedly: "If Umbraco supports a direct upgrade from version 13 to version 17, surely the upgrade itself is straightforward?"
It's a fair question and the answer is often misunderstood.
Yes, Umbraco officially supports a direct LTS-to-LTS upgrade path from Umbraco 13 to Umbraco 17. That's great news because it removes the need for multiple sequential platform upgrades and reduces some of the complexity that organisations faced in previous upgrade cycles.
What it doesn't mean, however, is that every Umbraco 13 website can be upgraded by simply changing a version number, deploying code and carrying on as normal.
The reality is that two websites running exactly the same version of Umbraco can require entirely different levels of effort to reach Umbraco 17.
The Version Number Only Tells Part of the Story
Imagine two organisations, both running Umbraco 13.
The first has a relatively straightforward website that uses standard Umbraco functionality, modern content editors and a small amount of custom development. The second has evolved over many years, accumulating integrations, bespoke workflows, custom backoffice functionality and layers of business-critical logic.
Technically, both organisations are asking for the same outcome: "Upgrade our website from Umbraco 13 to Umbraco 17."
In practice, they may be embarking on completely different projects.
This is why one organisation may complete an upgrade in a few weeks while another requires several months of planning, development, migration and testing.
The complexity rarely comes from Umbraco itself. More often, it comes from everything that has been built around it.
Your Website Is More Than a CMS
One of the biggest changes introduced in recent versions of Umbraco is the modernisation of the backoffice architecture.
Many organisations won't notice this change immediately because it sits behind the scenes. However, organisations that have invested heavily in custom editor experiences often discover that the backoffice deserves just as much attention as the public website.
Over the years, many Umbraco implementations have been extended with custom dashboards, bespoke property editors, content management tools, workflow enhancements and integrations embedded directly within the CMS.
Those customisations don't automatically move across to the new architecture. Each one needs to be reviewed and assessed. Some may require minor updates, while others may need to be rebuilt entirely.
As a result, the key question isn't simply whether Umbraco 17 supports your content. It's whether the ecosystem of custom functionality that supports your editors has a clear path forward.
Legacy Content Can Turn an Upgrade into a Migration
Content structures are another factor that can dramatically affect project complexity.
Many long-running Umbraco websites still use technologies such as Nested Content or the legacy Grid editor. Both have been superseded by modern Block List and Block Grid editors, which are now the preferred approach for building flexible content structures.
Where older implementations are present, an upgrade often becomes more than a technical exercise. It becomes a content migration project.
Data types, page content, rendering logic, templates and custom business rules may all need to be transformed before they can take advantage of the newer editor model.
This is why assessments matter. The scale of migration work often cannot be accurately measured until the implementation and content model have been properly reviewed.
You're Upgrading More Than Just Umbraco
A common misconception is that the move from Umbraco 13 to Umbraco 17 is purely a CMS upgrade.
In reality, there's another significant platform upgrade happening at exactly the same time.
Umbraco 13 runs on .NET 8.
Umbraco 17 runs on .NET 10 LTS.
Because Umbraco aligns its long-term support releases with Microsoft's .NET lifecycle, organisations benefit from a modern and fully supported technology stack. However, it also means that every Umbraco 13 to 17 project involves two major platform transitions simultaneously. You are moving:
Umbraco 13 to Umbraco 17
.NET 8 to .NET 10
For straightforward websites, this may have little impact. For mature digital platforms, however, it creates another layer of investigation.
Dependencies need to be reviewed. NuGet packages must be compatible with the new framework. Authentication solutions, middleware components, background services and deployment pipelines may all require updates.
In some cases, a seemingly simple CMS upgrade uncovers libraries or components that have not been maintained for years and are no longer compatible with modern frameworks.
That's why experienced upgrade teams start by assessing dependencies rather than discovering issues halfway through development.
Integrations Are Often Where Surprises Appear
The longer a website has been in service, the less likely it is to be operating in isolation.
Many modern Umbraco platforms are connected to CRMs, marketing automation tools, payment providers, search platforms, membership systems, authentication services and internal business applications.
These integrations often sit quietly in the background, working reliably for years.
An upgrade changes the equation.
Every integration needs to be verified, tested and in some cases updated to ensure it continues to function correctly within the upgraded environment.
We've seen situations where a website with thousands of simple content pages is far easier to upgrade than a smaller site with multiple business-critical integrations.
Page count rarely tells the full story.
Technical Debt Has a Habit of Appearing During Upgrades
Every mature website contains some degree of technical debt - that's perfectly normal.
Platforms evolve, business requirements change, developers move on and temporary solutions sometimes become permanent. As long as everything continues to function, there is rarely a compelling reason to revisit those decisions.
Until the upgrade begins.
Major upgrade projects often uncover packages that are no longer maintained, custom code that lacks documentation or integrations that nobody has touched for years.
The positive side is that upgrades create an opportunity to address these issues properly.
The challenge is identifying them early enough to plan accordingly.
Testing Is Often the Largest Hidden Effort
Getting a solution to compile successfully on Umbraco 17 is only one milestone. The real question is whether the organisation can continue operating exactly as it did before.
Can editors still publish content?
Do forms continue to submit correctly?
Do integrations exchange data successfully?
Can users authenticate and access restricted content?
Do search, redirects and scheduled jobs behave as expected?
The more business-critical the platform, the more comprehensive the testing effort becomes.
This is often one of the most underestimated parts of an upgrade project.
Why Organisations Shouldn't Leave Upgrades Until the Last Minute
Many organisations delay upgrades for understandable reasons:
The website appears to be working.
Other projects take priority.
Budget has been allocated elsewhere.
The danger lies in assuming the eventual upgrade will be straightforward.
If an assessment reveals a simple project, that's excellent. - you can schedule it confidently and move forward.
However, if the review uncovers legacy content structures, unsupported packages, complex integrations or significant technical debt, the project may require substantially more effort than originally anticipated.
Discovering that six months before end of life is manageable, but discovering it six weeks before end of life is considerably more difficult.
Our Recommendation: Investigate First, Upgrade Second
After completing numerous Umbraco upgrades, we've found the most successful projects all begin in the same place.
Not with development, but with understanding.
Before committing to timelines, budgets or delivery plans, assess the existing solution. Review the content model, packages, custom code, integrations and underlying .NET dependencies. Identify risks early and build the upgrade plan around evidence rather than assumptions.
Sometimes that assessment confirms a simple and straightforward upgrade path.
Sometimes it uncovers challenges that require additional planning.
Either outcome is valuable because it replaces uncertainty with clarity.
And right now, certainty may be the most valuable thing organisations running Umbraco 13 can buy.