Keeping Umbraco up to date isn’t just about staying current - it’s about stability, security, and making sure your content team doesn’t lose their rhythm. But version jumps, especially across .NET changes, aren’t something you want to wing. From backend refactoring to editor-side changes and infrastructure tweaks, a good upgrade is more than a checklist - it’s a process that needs planning, testing, and real awareness of what’s changed under the hood.

Keep It Current or Fall Behind: Why Upgrades Aren’t Optional

Umbraco aligns with .NET LTS releases, such as .NET 8 in v13, but does not release with every Microsoft .NET version. That’s good for long-term stability, but it also means upgrades aren’t something you can push off indefinitely. Sit on an old version too long, and you start to lose more than just feature updates - you risk running unsupported code, falling behind on security patches, and hitting blockers when it’s time to scale or integrate something new.

The shift from Umbraco 8 to 10+ involves moving from .NET Framework to .NET Core. Current target is .NET 8 (LTS) with Umbraco v13. - and that changes how things run under the hood. In .NET 6+, async patterns are strongly encouraged and used in new APIs, but existing synchronous code must be reviewed and updated. Deployment is cleaner. Performance improves across the board. But it also means older patterns need to be refactored, or things break.

For content teams, the good news is that the editor interface stays familiar. But for developers and ops, the upgrade is where you lay the groundwork for future flexibility. Do it early, and you can treat it as a smart evolution. Wait too long, and it turns into recovery work. Either way, the longer you wait, the more work you’re stacking up.

Before You Upgrade: What You Need to Get Right

Upgrading Umbraco isn’t just a technical task - it’s a shift in how your system behaves. If you're moving from version 8 or 9 to 10+, you're also migrating to a new .NET foundation. That changes how the code runs, how integrations behave, and how stable your future releases will be. Here’s what to focus on before writing a single line of migration code.

Map Out What You're Actually Running

Start by taking inventory. What version of Umbraco are you using? Are you still on .NET Framework? What packages are installed, and which ones are critical to daily operations? Make sure you understand what’s custom-built and what’s third-party. Some packages don’t survive a version jump. Some features you added manually might already be built into newer versions.

This is also where most teams discover undocumented dependencies or brittle workarounds baked into the system. Better to uncover that early than to run into it mid-upgrade.

Know What Changes Under the Hood

The jump to .NET 6 or later means async is the default. Anything written in old synchronous patterns - especially rendering code - needs to be reviewed. You’ll also want to pay attention to how forms are stored, how sessions are managed across multiple servers, and how authentication works now. If you use Azure Active Directory or custom identity setups, double-check how those integrate in the new version.

You’re not just patching - this is foundational work. It’s what makes future upgrades cleaner and less risky.

Decide If It’s an Upgrade or a Rebuild

Not every project needs a full rewrite - but some do. If you’re sitting on a heavily customized Umbraco 7 or 8 instance with outdated packages and no CI/CD in place, an in-place upgrade might create more problems than it solves. 

In those cases, spinning up a clean install and migrating content + logic selectively can save time and give you a more maintainable setup in the long run. Think in terms of outcomes. Stability. Editor usability. Dev efficiency. The right approach is the one that supports all three without creating technical debt.

What an Umbraco Upgrade Looks Like with OSKI Solutions

At OSKI Solutions, we upgrade Umbraco the way we handle any core system: with planning, structure, and attention to what actually changes under the hood. Most of our clients run mid-sized B2B operations where the CMS connects to more than just content - CRMs, ERPs, payments, internal tools. A version bump here affects real workflows, and we treat it accordingly.

We start with a technical audit. We review custom code, dependencies, and integration points. If the codebase is in good shape, we upgrade in place. If it’s not, we build new and migrate content with a cleaner setup. Either way, we keep things stable for editors and predictable for dev teams. You can explore some of our Umbraco projects or team insights on LinkedIn if you're curious what that looks like in practice.

What Can Break (and What Needs Attention)

Even if the upgrade runs clean, there’s still plenty that can misfire under the surface. These areas usually need a second look:

• Synchronous code in an async-first platform: Older rendering logic that isn’t async can slow down performance or trigger unstable behavior after deployment.
• Updated authentication and login flows: External providers like Azure AD or Google may need reconfiguration. Session handling and claims mapping often shift in .NET Core.
• Forms storage moved to the database: In Umbraco Forms v10+, form entries are stored in the database by default instead of disk files. This improves reliability but may require changes to deployment or backup workflows.
• Multi-server setups need proper key sharing: Without configured data protection keys, sessions may fail across load-balanced environments. Sticky sessions aren’t a real fix.
• Third-party integrations may lag behind: Some packages and custom APIs break quietly after a version jump. Even familiar tools need validation in the new stack.
• Legacy frontend logic can misfire: Templated behavior or layout rules from older builds may not run correctly with updated rendering engines.

Umbraco upgrades aren’t just about pushing to production. What matters is how well things hold up once users start clicking around.

Getting It Live Without Surprises

A successful upgrade doesn’t end when the site compiles. Stability comes from what happens next - how you test, when you cut over, and what safeguards are in place when real users hit the new system.

1. Pre-Launch Testing: Cover More Than Just the Basics

Testing isn’t just about catching bugs - it’s about confirming workflows, permissions, and integrations behave as expected across environments. Don’t assume that “it worked locally” means it works in production.

What to test before launch:

• Editor workflows: Make sure content updates, previews, publishing, and media uploads run cleanly in the new back office.
• User roles and permissions: Confirm access levels for admins, editors, and external users are still accurate after the upgrade.
• Custom integrations: Test all API calls, webhooks, and third-party systems - especially anything tied to CRMs or payments.
• Search and indexing: Rebuild indexes and check that search behaves correctly across content types and languages.
• Form submissions and notifications: Validate form handling, storage, and any automated email or webhook behavior tied to submissions.

2. Cutover Strategy: Minimize Downtime, Maximize Control

When switching from the old site to the upgraded one, the handoff needs to be predictable. Parallel environments can help avoid downtime and give space for controlled testing.

Cutover best practices:

• Deploy to new infrastructure: Stand up a clean production environment for the upgraded build - don’t overwrite the live instance.
• Run both systems in parallel: Keep the old site live while testing the new one behind a restricted URL or VPN. Compare behavior under real usage.
• Prepare DNS or reverse proxy rules: Plan your final switch early - whether it’s a DNS update or a load balancer config, this step shouldn’t be rushed.

3. Post-Launch Monitoring: Don't Assume It's Over

Once the switch is live, watch it. Even well-tested deployments can reveal edge cases only visible under full user traffic.

What to monitor right after launch:

• Error logs and exception handling: Track for unexpected errors - especially from custom code or packages that passed basic testing.
• Performance metrics: Monitor page load times, API latency, and database calls. Upgrades should feel faster, not heavier.
• User-reported issues: Create a clear feedback channel for editors and users to flag issues quickly.

A clean upgrade isn’t just one step - it’s a set of decisions that reduce surprises. Plan it right, and launch day becomes routine - not a fire drill.

Where Teams Get Stuck (and How to Avoid It)

Even well-planned upgrades can hit friction points - usually in places that don’t show up until it’s too late. These aren’t rare bugs. They’re predictable missteps that surface when details get skipped or assumptions go unchecked. Here’s where most teams lose time, and how to avoid doing the same.

Skipping the Technical Audit

Many teams jump straight into the upgrade assuming their codebase is ready. But without a full audit - packages, rendering logic, configuration, session handling - it’s easy to miss compatibility issues that only appear under real traffic. 

Even small mismatches in async handling or authentication setup can quietly break parts of the system later. An upgrade should begin with a full scan of what’s running today, not just a review of the main repo.

Overlooking Editor and Content Needs

Upgrades aren’t just a dev task - they reshape the tools editors use every day. Failing to validate permissions, publishing flows, or block layouts often leads to frustrated content teams and rushed hotfixes post-launch. 

It’s not enough that the back office loads. You need to confirm the entire editorial process works just as expected - or better - after the upgrade.

Rushing the Cutover

Trying to switch environments too fast is a common misstep. Without proper overlap between old and new instances, teams miss the chance to compare behavior, confirm infrastructure settings, or validate caching strategies under pressure. Cutover planning isn’t just about scheduling - it’s about having room to step back, monitor, and make controlled decisions when things go live.

Not Owning the Follow-Up

Once the new version is live, the real test begins. Teams that stop monitoring after launch miss slow-fail issues - like broken analytics, background errors, or degraded performance during high traffic. The follow-up window is critical. That’s where stability is proven, integrations are stress-tested, and the upgrade becomes more than just a version bump.

Conclusion

Upgrading Umbraco isn’t a one-click task, but it’s not something to fear either. With the right prep, a clean audit, and clear expectations between developers and editors, the process becomes manageable - and, more importantly, repeatable. The key is treating it like a systems change, not just a version change. 

When you build in time for testing, validate every layer, and plan the launch with room to monitor and adjust, you avoid the common traps. And if you’re already overdue for a major upgrade, it’s better to do it with intent than wait until something forces your hand. Structure now saves cost later.

FAQ