The Honest Umbraco 13 to 17 Upgrade Guide

What migrates, what breaks, and what hurts

The first three posts in this series made the case for upgrading to Umbraco 17. This one is for the person who has to actually do it. If you're upgrading from Umbraco 13 to Umbraco 17, some things migrate automatically. A lot of things don't. No "smooth and seamless." Just what auto-migrates, what breaks, what's a known bug, and where the people who have already done this lost the most time.

What Umbraco does for you

Two big things migrate automatically when you boot a v17 site against a v13 database for the first time.

Dates move to UTC - Per the official version-specific upgrade docs, "system dates are now always stored in UTC, and a migration will run when upgrading to Umbraco 17 to ensure existing stored system dates align." If your old site stored anything in local time and your team works across regions, this is the one-time correction you've been waiting for.

Rich-text content moves from TinyMCE to Tiptap - "Umbraco automatically migrates existing RTE content to TipTap as part of its standard migration, with existing content remaining intact, but datatypes needing review." Most pages survive the move cleanly. The pages that don't are the ones with embedded blocks, custom inline patterns, or older macros. Test the pages that use your RTE the most. Don't assume.

That's the help you get for free. Everything below is on you.

What you have to do yourself

Update the .csproj file to target .NET 10 - Your project file gets a one-line edit that triggers a chain reaction across every dependency. Some NuGet packages will need updating to versions with .NET 10 support. Others may not be compatible with your target version yet. That is how you discover which third-party packages in your stack are actively maintained.

Rewrite custom backoffice extensions - Covered at length in the previous post, the v14 backoffice rewrite means anything you wrote against AngularJS no longer has a home. If you have more than a handful of custom property editors, dashboards, or tree views, this is where most of your project budget will go.

Strip out middleware that's no longer needed - The upgrade docs note that "some middleware is no longer required in Umbraco 17 and should be removed from the startup pipeline." Specifically: review your `Program.cs` / `Startup.cs` against the v17 reference and delete anything that's now baked in. Leaving it in doesn't always break things, but sometimes it does, and the failure mode is often quiet.

Update calls to deprecated APIs and services - Per the same docs, "a few APIs and services used in earlier versions are deprecated or removed, which means existing custom code may require updates to align with the newer Umbraco patterns and services." Don’t shortcut here. Compile the project, fix what breaks, work through the deprecation warnings, and run your test suite. The authoritative diff is the official compare 16.4.0 → 17.0.0 changelog, and it's worth reading end-to-end before you start cutting code.

Re-license Umbraco Forms if you use it - This catches finance teams off-guard. Per the same docs, "you may need to migrate to the new licensing structure, which is now licensed annually instead of a one-time cost." If you bought a perpetual Forms license years ago, that model is gone. Loop in whoever owns the budget for software licenses before the upgrade, not after.

Known bugs to watch

The RTE migration is the area I’d test hardest. There have been multiple v13-to-v17 bugs involving TinyMCE-to-Tiptap content, including inline blocks moving out of position, legacy block references not migrating cleanly, HTML structure changing, and some blocks losing their published state.

A good starting point is GitHub issue #21204, but don’t stop there. Check the current v17 issues and release notes against the exact version you’re deploying.

If your v13 site uses inline blocks, block-level RTE content, or custom HTML inside the rich-text editor, build a focused QA list before you migrate.

The recommended sequence

The version-specific docs are unambiguous on one point: don't skip v13 patch updates before you start. "Ensuring all v13 level migrations are already applied provides a stable base before moving to v17." Get to the latest 13.x first, run that build for at least a deploy cycle, then begin the v17 work. Trying to combine "catch up on patches" with "jump three majors" makes failure modes hard to attribute.

The realistic plan

1. Patch your v13 install to the latest. Run it for a sprint. Confirm clean.
2. Inventory custom backoffice extensions, custom property editors, and any AngularJS frontend bits.
3. Spin up a v17 dev environment. Migrate a copy of production. Boot it and read every warning.
4. Walk the changelog end-to-end. Note the deprecated APIs you actually use.
5. Rebuild extensions. Update middleware. Re-license Forms if applicable.
6. Content QA with a focus on RTE-with-blocks pages. Check current v17 migration issues and release notes for the exact version you're deploying. 
7. Performance test in staging before cutover.
8. Ship it.