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, and leftover updating markers.

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
​

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:9
error: 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. Navigate to site > locks.

  3. Locate the file named updating.

  4. Delete it.

  5. 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.

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.

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 July 27, 2026

Did this answer your question?