Type: Troubleshooting
Category: Umbraco Cloud > CI/CD & Deployments
Tags: version conflict, version mismatch, package downgrade, Umbraco.Forms.Web, Umbraco.Forms.Core.Providers, automatic upgrade failed, deployment, dependency errors, portal version display, backoffice version, database cache

Product: Umbraco Cloud, Umbraco Forms
Version: All versions

Version problems on Umbraco Cloud usually fall into one of two groups: an upgrade that fails because two package references disagree about which version to install, and an upgrade that succeeded but where a version number somewhere still reads as the old one. The two need different handling, so start by working out which one you have.

Which problem do you have?

The upgrade failed with a downgrade or version conflict error in the build or deployment log. Go to Upgrade fails with a package downgrade or version conflict.
The upgrade completed and the site works, but a version number still shows the old value. Go to The upgrade succeeded but a version number still shows the old value.
Neither quite fits, and the deployment is failing for another reason. See Environment issues in Umbraco Cloud for schema mismatches, pending changes and environment restarts.

Upgrade fails with a package downgrade or version conflict

Symptoms

An automatic upgrade, or a local package upgrade, fails with a package downgrade error naming an Umbraco Forms package such as Umbraco.Forms.Web or Umbraco.Forms.Core.Providers.
The error describes one package resolving to a lower version than another package requires.
Retrying the upgrade fails in the same way.

Cause

Umbraco.Forms is the package you are meant to reference. The sub-packages it depends on, including Umbraco.Forms.Web and Umbraco.Forms.Core.Providers, are pulled in automatically at matching versions.

If a project also references one of those sub-packages directly, that reference pins a version independently. An upgrade then targets Umbraco.Forms, the pinned sub-package stays where it is, and the two no longer agree. NuGet reports this as a downgrade rather than resolving it.

Solution

Find the direct references. Open your project's .csproj and look for any PackageReference to an Umbraco Forms sub-package. Only Umbraco.Forms should be listed:
```
<PackageReference Include="Umbraco.Forms" Version="xx.x.x" />
```
Remove the sub-package references. Delete the PackageReference lines for Umbraco.Forms.Web, Umbraco.Forms.Core.Providers, and any other Forms sub-package, leaving only Umbraco.Forms.
Upgrade Umbraco Forms manually. Set Umbraco.Forms to the version you are targeting, then restore. Confirm nothing else in the solution reintroduces a sub-package reference at a different version.
Verify locally. Run the project and log in to the back office before deploying anything.
Push to Cloud. Deploy the resolved solution through your environment chain. Fixing the conflict locally first is what keeps the environments consistent.

If you need a sub-package reference for a reason. Custom Forms code sometimes leads people to reference a sub-package directly. If you cannot remove it, it has to be held at exactly the same version as Umbraco.Forms and updated in step with it, every time. Referencing only Umbraco.Forms is the supported arrangement.

The upgrade succeeded but a version number still shows the old value

Here the important question is where you are reading the old version, because the answer is different for each place.

The back office is the authoritative source

Click the Umbraco logo in the back office of the environment you are checking. The version shown there comes from what that environment is actually running.

The back office version is not a cached display. If the back office of an environment reports the old version, treat that environment as still running the old version and work through the deployment, rather than waiting for a cache to clear.

If only the Cloud portal shows the old version

Confirm the environment's back office reports the new version, and that the site behaves as the new version.
If it does, the portal display is simply behind. Cached version-check responses can show a stale value for a while, and a project with a long deployment history can make those checks slow enough to delay the update.
Give it time and re-check. There is nothing to fix in your solution.

If the environment's own back office shows the old version

This is not a display problem, and waiting will not change it. Check, in this order:

Did the deployment complete? Open Project History in the portal and confirm the deployment finished rather than stopping partway. Read the Kudu deployment log for the deployment in question.
Did the build succeed on the target? A deployment can show as pushed while the build on the environment failed, which leaves the previous version running.
Is the .NET version right for the target major? A major upgrade usually needs a newer .NET runtime. Check Configuration > Advanced > Runtime Settings in the portal for that environment, and global.json in your solution.
Are you looking at the right environment? Open the back office from Overview > Environments in the portal rather than from a saved URL.
Try a small follow-up push. Make a minor change locally and deploy again. This sometimes completes an upgrade that stalled.

Do not keep waiting. If an environment's back office has reported the old version for more than a few minutes after a completed deployment, contact support rather than continuing to wait. Time spent waiting on a cache that is not the cause is time the upgrade sits half-applied.

Prevention

Reference only Umbraco.Forms, never its sub-packages, so automatic upgrades have nothing to conflict with.
Upgrade and verify locally first, then deploy. Do not upgrade directly on a Cloud environment.
Check the version by clicking the Umbraco logo in the target environment's back office, not by reading the portal.
Keep the .NET runtime setting aligned across Development, Staging and Live before starting a major upgrade.

Still having issues?

Contact Umbraco Cloud support with the environment concerned, the version you expect, the version the back office reports, and the deployment log for the relevant deployment. If you are already in a support conversation, ask to talk to a human agent.

How do I troubleshoot version conflicts or mismatches during Umbraco Cloud deployments?