Unity 6 Upgrade Checklist: The Blockers Nobody Warns You About

Most “upgrade to Unity 6” guides hand you the official release notes and wish you luck. The problem is that the things that actually block a real project — the ones that turn a one-hour upgrade into a three-day slog — are scattered across a dozen pages. This is the checklist of the blockers that bite hardest, in roughly the order you’ll hit them.

Before you start: back up your project (or commit everything to version control), and upgrade through LTS versions in release order — if you’re on 2021, skim the 2022 upgrade notes before jumping to 6. Skipping versions hides breaking changes.

1. Deprecated and removed scripting APIs

The first wave is compile warnings and errors from obsolete APIs. The most common is the FindObjectOfType / FindObjectsOfType family, now replaced by FindFirstObjectByType, FindAnyObjectByType, and FindObjectsByType. There are many others, each located somewhere in your scripts.

These are usually mechanical renames, but you have to find every call site. (We wrote a dedicated FindObjectOfType migration cheatsheet for that one.)

2. UI Toolkit event API changes (the #1 reported headache)

If you use UI Toolkit, this is the single biggest source of upgrade pain. Unity migrated all the standard controls to new event methods, and mixing obsolete and new methods can put your event logic out of sync — so partial migration is worse than none.

The core replacements:

  • ExecuteDefaultAction / ExecuteDefaultActionAtTarget → HandleEventBubbleUp
  • PreventDefault → StopPropagation (or just remove it if StopPropagation already ran in the same block)

The tricky case: old code calling PreventDefault during a BubbleUp callback can’t simply become StopPropagation, because the event has already reached its target. The fix is to add a callback during the TrickleDown phase and call StopPropagation there instead. Expect to also clear out obsolete uxmltraits warnings.

3. Obsolete graphics formats = hard compile errors

Several graphics formats that were merely deprecated in 2022.1 are now obsolete and produce compile errors in Unity 6. GraphicsFormatUtility.GetGraphicsFormat also stopped returning the obsolete formats — for example it now translates RenderTextureFormat.Depth to GraphicsFormat.None instead of DepthAuto. If you touch RenderTextures or graphics formats in code, audit these explicitly; they won’t just warn, they’ll stop your build.

4. Package versions vs. your editor version

A subtle but very common blocker: a package in your Packages/manifest.json may declare a minimum Unity version newer than the editor you’re on (or vice versa). The classic example is a render-pipeline package (URP/HDRP) that requires Unity 6000 while your editor is still 2022.3. This surfaces as confusing compile/resolve errors rather than a clear “incompatible” message.

Check each package’s compatibility against your target editor before upgrading — and if you use URP or HDRP, follow their dedicated render-pipeline upgrade guides, which have their own breaking changes separate from the core engine.

5. Input System: both backends enabled

If your project has Active Input Handling set to “Both” (the old and new input systems running together), now is the time to converge on one. Keeping both enabled carries runtime overhead you no longer need post-migration. Confirm in Project Settings → Player → Active Input Handling.

6. Silent visual changes (not errors, but they’ll surprise you)

Some changes don’t break the build — they change how your game looks, which is worse if you don’t expect it:

  • Light Probes are brighter. Previously Unity’s Light Probes were only ~94% as bright as they should be, so probe-lit objects looked slightly darker than lightmapped ones. Unity 6 fixes this, so probe-lit scenes can look noticeably different after upgrading. If your lighting shifted, this is likely why.

7. Editor menu / template breakage (for tooling authors)

If you’ve extended the editor, note the Assets/Create menu was reorganized and the built-in ScriptTemplate files were renamed. Custom entries added via CreateAssetMenuAttribute, MenuItemAttribute, or custom ScriptTemplates may land in different positions, and any code that calls EditorApplication.ExecuteMenuItem with a hardcoded menu path needs the new path.

A pragmatic upgrade order

  1. Commit/branch first. Upgrade the editor on a throwaway branch.
  2. Get it to compile: fix obsolete-API errors (APIs, graphics formats) and resolve package version mismatches.
  3. Fix UI Toolkit event code fully (no partial migration).
  4. Converge input backends; clear remaining warnings.
  5. Do a visual pass — check lighting/probes against the old build.
  6. Build to device and profile before merging.

Let PerfLint surface the blockers up front

The worst part of a Unity 6 upgrade is not knowing the size of the job until you’re deep in it. PerfLint for Unity’s Migration scan runs locally and gives you the list before you commit: deprecated/removed APIs located to the exact line with replacements (MIG.FindObjectOfType and more), package-vs-editor compatibility checks (MIG.PackageUnityIncompat), mixed input-backend detection (MIG.InputBackendBoth), and a manifest.json preview. Safe renames can be applied as compile-verified one-click migrations with automatic rollback. Nothing is uploaded. Run a free scan →

FAQ

Should I upgrade straight from 2021 to Unity 6? You can, but read the intermediate (2022 LTS) upgrade notes first and upgrade in release order — skipping versions hides breaking changes. Always back up / branch first.

Why does my UI break after upgrading to Unity 6? Almost always the UI Toolkit event API changes. Replace ExecuteDefaultAction(AtTarget) with HandleEventBubbleUp and PreventDefault with StopPropagation, and migrate fully — mixing old and new methods desyncs event logic.

Why does my scene look brighter/different after the upgrade? Unity 6 corrected Light Probe brightness (they were ~94% before). Probe-lit objects are now as bright as lightmapped ones, so lighting can shift visibly.

My package throws errors after upgrading — why? Likely a package whose required Unity version doesn’t match your editor. Check Packages/manifest.json versions against your target editor, and follow the dedicated URP/HDRP upgrade guides if you use them.

Rule reference: MIG.PackageUnityIncompat · MIG.LegacyInputApi

← Back to all posts