Skip to main content

How to Troubleshoot Common Deployment Errors in Umbraco Cloud

Identify and resolve the most common Umbraco Cloud deployment errors, including data extraction failures, patch failures, busy environments, leftover updating markers, and deployments that report success without applying your changes.

Written by Joana Knobbe

Type: Troubleshooting
​Category: Umbraco Cloud > CI/CD & Deployments
​Tags: deployment error, data extraction failed, patch failed, cloud-sync, updating marker, environment busy, manual extraction, clear signatures, set signatures, Kudu, deploy-marker, changes not visible, skipped build, schema-only changes, RazorCompileOnBuild, precompiled views
​

Product: Umbraco Cloud
​Version: All versions (Deploy Dashboard steps require Umbraco Deploy 4+)

Deployment errors on Umbraco Cloud usually come down to one of a handful of causes: an environment that is still busy, a schema that has drifted out of sync, a leftover lock file, or code conflicts between your repository and the Cloud environment.

This article covers the most common ones and how to resolve each. Work through the section that matches your error message.

Always work left to right. Most deployment problems trace back to changes being made out of order across environments. See Deployment for the deployment model.

Error: "Awaiting deployment to finish"

Symptoms

The deployment appears to hang at the cloud-sync stage and never completes.

Cause

Usually an issue with the cloud-sync process, brought on by resource limitations or temporary server overload during deployment.

Solution

  1. Temporarily disable cloud-sync. If the deployment depends on cloud-sync, skip that step. Instructions for both GitHub Actions and Azure DevOps are in the CI/CD troubleshooting documentation.

  2. Run the deployment directly from your pipeline provider. In some cases, triggering the deployment manually from GitHub Actions or Azure DevOps gets past the issue. Check whether this is viable for your pipeline.

  3. Resolve any conflicts between your repository and the Cloud environment before re-enabling cloud-sync.

  4. Re-enable cloud-sync and retry once the conflicts are resolved.

Error: "The environment is busy with a deployment, try again later"

Symptoms

The Portal refuses a new deployment because another process is already running on the target environment.

Cause

The environment is engaged in another deployment or extraction and cannot accept a new request.

Solution

  1. Wait and retry. Large deployments can take several minutes.

  2. Restart the environment. This clears most stuck processes. See Restart or stop an environment.

  3. Run a manual extraction if restarting does not help. See the Manual extraction section below.

If the deploy-marker file is simply named deploy (rather than deploy-progress, deploy-complete or deploy-failed), the extraction cannot start. Restart the environment to let it run.

Error: "Data extraction failed"

Symptoms

A deployment reaches the Cloud environment, but the extraction step fails. The Portal shows an extraction error, and deploy-marker becomes deploy-failed.

Cause

The .uda files on disk cannot be deserialized into the database. This is most often caused by:

  • Cached artifact signatures that have drifted out of sync, typically after a major upgrade or a large schema change.

  • Conflicting or colliding .uda files between the two environments.

  • A schema item referenced by an artifact that does not exist in the target environment.

Solution

Step 1 — Read the actual error

Open the deploy-failed file in Kudu (site/wwwroot/umbraco/Deploy) or check the environment's log in the Portal. The exception type tells you which of the fixes below applies. Do not skip this step: the remedy for a colliding data type is different from the remedy for a stale signature, and applying the wrong one can make things worse.

Step 2 — Clear and re-set the cached signatures

Umbraco Deploy caches hashed signatures of your schema and content artifacts to speed up operations. After a major upgrade these can go stale or become corrupted, which is a common cause of extraction failures that look like schema mismatches.

  1. Open the backoffice for the affected environment.

  2. Go to Settings > Deploy > Status.

  3. Under Deploy Operations, run Clear signatures.

  4. Then run Set signatures to regenerate them for all entities.

  5. Restart the environment.

  6. Retry the deployment.

Step 3 — Update the schema

If the error points at a schema mismatch, run the Update schema operation from the same Deploy Operations panel. This updates the Umbraco schema from the .uda files on disk.

Step 4 — Match the error to a specific fix

If the error names a specific artifact or collision, follow the matching guide:

Step 5 — If a manual extraction fails with the same error, stop and contact support

A manual extraction runs the same engine, so it will reproduce the same failure. Repeating it will not change the outcome. At this point, contact Umbraco Cloud support with the full error and stack trace rather than deleting schema items or recreating environments. Recreating an environment to work around an extraction error can introduce further problems, including changes to your deployment pipeline order and loss of media.

Error: "Patch failed" / "Apply git patch to branch" fails in CI/CD

Symptoms

A CI/CD pipeline fails at the patch step with an error similar to:

error: patch failed: src/UmbracoProject/UmbracoProject.csproj:9error: src/UmbracoProject/UmbracoProject.csproj: patch does not apply

Cause

Conflicts between your source repository and the code in the Umbraco Cloud repository. Usually one of:

  1. Cloud project packages were auto-upgraded, and that diff was already applied on Cloud.

  2. The team is not following the left-to-right deployment model.

Solution

  1. Ensure your repository contains the changes that already exist in the Cloud environment.

  2. Resolve any conflicts manually.

  3. Run a new deployment that skips the cloud-sync step.

Step-by-step instructions for skipping cloud-sync in both GitHub Actions and Azure DevOps are in the CI/CD troubleshooting documentation. Re-enable cloud-sync once the deployment has succeeded.

If the patch failure persists after this, or the log shows Already Shadowing or ImportArtifactsUnhandledException, see Git Patch Failures and "Already Shadowing" Errors in Umbraco Cloud CI/CD.

Error: "The project's left-most mainline environment has changed"

Symptoms

The CI/CD 'get diff' endpoint returns a 409 with a LeftMostEnvironmentChanged payload.

Cause

You added or removed a mainline environment, so the mechanism that calculates changes since the last deployment can no longer do so.

Solution

  1. Manually ensure all the latest changes on your left-most mainline environment are present in your local copy.

  2. Run a new deployment that skips the cloud-sync step.

See CI/CD troubleshooting for the full procedure.

Error: "The site can't be upgraded as it's blocked with the following markers: updating"

Symptoms

Deployment is blocked by a leftover lock marker after a previous deployment failed and the infrastructure did not clean up.

Solution

  1. Access Kudu on the affected environment.

    • With one environment, use the Live environment.

    • With V1 endpoints and more than one environment, use the left-most mainline environment.

  2. Go to Debug console > CMD. The Debug Console is the reliable way to browse files in Kudu, and the "Files" tab does not work in all cases. See How can I access and manage files in my Umbraco Cloud project using Kudu?

  3. In the directory tree, navigate to site > locks.

  4. Locate the file named updating.

  5. Delete it.

  6. Run the deployment again.

Error: "Unable to verify the deployment has finished"

Symptoms

The system cannot confirm that the latest deployment was pushed and deployed in Kudu.

Solution

Check the Deployment Kudu Log on the Project History page first, then work through these:

  • Confirm your code compiles and runs (relevant if you have enabled the skipBuildAndRestore toggle in V2).

  • On Umbraco 15 or later, set CompressionEnabled to false. Static asset compression is resource-intensive and slows the Kudu deployment.

  • Avoid running npm commands via .csproj files. This is generally unsupported on Umbraco Cloud.

  • Commit a small change (a comment in a .cs file, or a dummy text file) and deploy again.

  • Check your artifact follows the artifact best practice.

Deployment succeeds but the changes are not visible

Symptoms

  • The deployment completes and the Portal reports success. There is no error and no deploy-failed marker.

  • The environment keeps serving the previous version of the site. Code changes, template changes, or static assets such as CSS and JavaScript do not appear.

  • Restarting the environment does not help.

  • After an upgrade, the Portal environment card and the backoffice may still report the previous version.

Cause

Several unrelated things produce this same symptom, and the deployment reports success in every one of them. Work through the steps below in order. The first two leave a trace in the deployment log that tells you which one you have, so read the log before changing anything.

Solution

Step 1 — Check whether the build was skipped

Umbraco Cloud skips the .NET build when it determines that the pushed changeset contains schema changes only. If a push is classified this way, your new code is never compiled, the environment carries on running the previous build, and the deployment still reports success.

  1. Access Kudu on the affected environment.

  2. Go to Debug console > CMD.

  3. Navigate to site > deployments and open the folder for the most recent deployment.

  4. Open log.log and look for a line containing:

Skipping dotnet build as changes only contains Schema changes

If that line is present, the build did not run. Force it by including a code file in the next changeset: add a comment or a blank line to a .cs file such as Program.cs, commit it, and deploy again.

This is why "make a small change and redeploy" sometimes works. It is not resetting a stuck pipeline. It is putting a code file into the changeset so the build runs. If the log does not say the build was skipped, a dummy commit is unlikely to change anything, so continue to the next step instead of repeating it.

Step 2 — Check whether a config transform failed

A failing XML config transform stops the extraction from completing, so no changes are applied even though the deployment reported no error.

  1. In Kudu, go to site > deployments and open the most recent deployment folder.

  2. If it contains only log.log and status.xml, with no commits.uc and no manifest, a transform failed.

  3. Search log.log for XmlTransform errors.

  4. Correct the XML syntax in the transform file and deploy again.

  5. Run a schema deployment from the data file to extract the schema. See Extraction error: Config transforms failing.

Step 3 — Check the extraction and the deploy marker

If the code is present but content or schema changes are missing, the extraction may not have run or may have failed quietly. Check the deploy-marker file as described in the Data extraction failed section above, and note that a marker left as deploy rather than deploy-progress, deploy-complete or deploy-failed means the extraction never started.

Step 4 — If templates specifically are not taking effect, check your project file

If the pages return Page Not Found and the log shows an error such as No physical template file was found for template "Home", while the .cshtml file is clearly present on the environment, the views are being precompiled.

  1. Open your .csproj file.

  2. Look for <RazorCompileOnBuild> and <RazorCompileOnPublish>.

  3. Remove both properties. Setting them to false is not enough, they have to be removed.

  4. Commit and deploy again.

These properties belong with ModelsMode set to InMemoryAuto. The Umbraco Cloud project template carries a comment to this effect next to them.

Step 5 — If none of the above applies

Contact Umbraco Cloud support with the deployment log from site/deployments for the deployment that did not take effect, and say which changes you expected to see. If you are already in a support conversation, ask to talk to a human agent.

Running a manual extraction

If you are on Umbraco Deploy 4 or later, run extractions from the Deploy Dashboard (Settings > Deploy) rather than Kudu. Use the Kudu method below only if the backoffice is unavailable.

  1. Access Kudu for the environment.

  2. Go to Debug console > CMD.

  3. Navigate to site/wwwroot/umbraco/Deploy.

  4. Run: echo > deploy

  5. The deploy-marker file changes to deploy-progress while the extraction runs.

  6. When it finishes, the marker becomes either deploy-complete (the extraction succeeded) or deploy-failed (open the file to read the error).

The /Deploy folder also contains a Revision folder with your project's UDA files, and deploy.log with logs from the latest extraction.

Key considerations

  • Always follow the left-to-right deployment model (Development > Staging > Live).

  • Read the deployment logs before acting. The specific exception determines the fix.

  • Keep local and remote repositories in sync to avoid patch conflicts.

  • Let your team know when auto-upgrades have been applied to a Cloud environment.

  • Do not delete schema items or recreate environments as a first response to a deployment error. Both are difficult to undo.

  • A deployment that reports success has not necessarily built your code. If changes do not appear, read the deployment log before assuming the pipeline is at fault.

Still having issues?

If the error persists after working through the relevant section, contact Umbraco Cloud support with the full error message and stack trace from deploy-failed or the environment log. If you are already in a support conversation, ask to talk to a human agent.

Recommended documentation

Last updated on August 18, 2026

Did this answer your question?