Troubleshooting

Learn how to troubleshoot and debug different scenarios you might encounter while using the CI/CD feature.

Special Cases

Using RestorePackagesWithLockFile in your .csproj file

If RestorePackagesWithLockFile is set to true, you will experience that no changes are made to the website.

This happens even though the CI/CD deployments were successfull, and files were updated as expected in the Cloud repository. The reason for this is that the Kudu deployment process fails. This process takes the newly committed files from the Cloud repository and runs the restore, build, and publish operations on the Cloud environment.

How to resolve the issue

To resolve this issue, remove RestorePackagesWithLockFile for deployments to go through as expected.

Deployment report: No changes detected - cleaning up

The package you uploaded didn't contain any changes that would affect the Git repository on the Cloud Environment. The CI/CD job will skip the remaining steps and complete.

How to resolve the issue

If you expected the deployment to create changes in the Cloud Environment, make sure you are uploading the correct ZIP file.

Cloud Sync

The project's left-most mainline environment has changed

The mechanism to determine changes since the last deployment can't do so when the left-most mainline environment has changed.

This happens when you either add or remove a mainline environment. The 'get diff' endpoint responds with status 409 and the following JSON payload:

{
  "type":"LeftMostEnvironmentChanged",
  "title":"The projects left-most environment has changed",
  "status":409,
  "detail":"Unable to calculate changes based on a different left-most environment",
  "traceId":"..."
}

How to resolve the issue

You need to manually ensure that all the latest changes on your left-most mainline environment are also present in your local copy.

Once this is done, you can run a new deployment that skips the cloud-sync step.

• How to skip cloud-sync in GitHub

• How to skip cloud-sync in Azure DevOps

If you experience problems with your environment not properly booting up after deployment, read the Unable to determine environment by its {environment-id} guide.

“Apply Remote Changes” step is failing

The sample pipelines are naively trying to apply any changes from the generated patch file on the Cloud. This doesn't always work, and you might see an error similar to the following:

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

The root cause is due to conflicts between your source and the code in the repository on Umbraco Cloud. This is usually due to one of two things:

1. The Cloud project package(s) have been auto-upgraded, and that diff was already applied.

2. You and your team are not following the "left to right" deployment model.

How to resolve the issue

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

2. Resolve any potential conflicts manually.

3. Run a new deployment without the cloud-sync step.

How to skip cloud-sync in GitHub

For Azure DevOps, see the Skip cloud-sync in Azure DevOps section.

1. Ensure your GitHub repository is up-to-date with any changes in your Umbraco Cloud environment.

2. Locate the main.yml file in the following directory: {projectname}.github\workflows on your local project.

3. Open the main.yml file in a text editor and navigate to the “jobs” section.

4. Comment out the entire “cloud-sync” section and the “needs: cloud-sync” under “cloud-deployment”.

The screenshots below provide an example:

Cloud sync code highlight

1. Commit the changes and push them to GitHub. This action will trigger a build and run the pipeline.

At this point, the pipeline should execute successfully, and your changes will be pushed to Umbraco Cloud. If this is the case, proceed to the next step.

1. Remove the comments added in step 4 and make a new commit.

   1. Optional: Add "[skip ci]" to the last commit message, to avoid automatically triggering the pipeline

2. Push these changes to GitHub.

Your pipeline should now function as expected.

How to skip cloud-sync in Azure DevOps

For GitHub, see the Skip cloud-sync in GitHub section.

1. Navigate to your azure-release-pipeline.yaml and comment out these two lines:

dependsOn: cloudSyncStage
condition: in(dependencies.cloudSyncStage.result, 'Succeeded', 'Skipped')

1. Ensure that your Azure DevOps repository is up to date with any changes in your Umbraco Cloud environment.

2. Find the pipeline in Azure DevOps.

3. Click on "Run Pipeline" in the top right corner.

Run Pipeline in Azure DevOps

1. Click on "Stages to run."

The Run Pipeline View

1. Uncheck the "Umbraco Cloud Sync" checkbox.

2. Confirm on "Use selected stages".

The Stages to run View

1. Click on "Run" back in the "Run Pipeline" view.

As no changes were made to your pipeline, it will run as usual on the next push to Azure DevOps.

Upload Errors

Failed to read the request form. Multipart body length limit 134217728 exceeded

The current size limit is set to 134217728 bytes (or about ~128 MB).

How to resolve the issue

Ensure that the package you are trying to upload does not contain any unnecessary items.

You can see an example of how to zip your repository before uploading it, by referring to our GitHub or Azure DevOps samples.

Deployment failed

File missing: The .umbraco file cannot be found in the root of the repository

The .umbraco file is missing or has been renamed. This file must be present at the root of the zip file.

Below is an example of the default .umbraco file that comes with a new Umbraco Cloud project.

[project]
base = "src/UmbracoProject"
csproj = "UmbracoProject.csproj"

File format Error: The .umbraco file is not valid

The .umbraco file has invalid characters. Sometimes you might need to change the repository's folder structure and the default project's name. Ensure that the base field does not use backslashes ('') as the folder denominator.

See an example of the default .umbraco file in the section above.

Cannot apply update because the following packages would be downgraded: Package: Umbraco.{abc}, Version: {x.y.z}

The service goes through all .csproj files in the uploaded package and compares them to the versions running in your left-most cloud environment. This is done to try to prevent you from downgrading the crucial Umbraco packages used by the cloud.

The full error could look like this:

Cannot apply update because the following packages would be downgraded: Package: Umbraco.Cms, Version: 13.4.0 ==> Project file: /Update/src/MyAwesomeProject.Code/MyAwesomeProject.Code.csproj contains lower Version: 13.1.0 .

The error tells you which package to look for and which version is currently in your left-most cloud environment. The error also contains the problematic incoming .csprojfile and the version referenced by it.

If the incoming package references multiple lower-versioned packages, the error will list each one.

How to resolve the issue

Align the package versions in your .csproj files with the higher version mentioned in the error for that package.

If you have orphaned .csproj files, remove or rename them. Orphaned would be backup .csproj files or files not referenced by any of the main project files nor referenced in a .sln file.

Could not find /app/work/repository/Readme.md to stat: No such file or directory

In some cases, you might see an issue where filename casing causes an error.

How to resolve the issue

1. Rename the Readme.md file in the root of your repository to something different. The file can keep the markdown extension.

2. Commit the change to your repository.

3. Run the pipeline.

If you want, you can change the filename back to Readme.md after a successful CI/CD deployment.

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

In rare cases, deployments fail, and the Cloud infrastructure doesn't clean up correctly. This leaves behind an "updating" marker. The next time you try to deploy through your pipeline, you will encounter an error.

How to resolve the issue

To fix this issue, use Kudu to remove the leftover marker file.

1. Access Kudu on the affected environment.

   1. If you only have one environment, you want the live environment.

   2. If you use V1 endpoints and have more than one environment, you want the left-most mainline environment.

2. Navigate to the site > locks folder.

3. Locate the file named updating.

4. Remove the updating file.

5. Run the pipeline to verify whether the issue has been resolved.

Unable to verify the deployment has finished

This error will be shown when the system can't verify that the latest deployment has been pushed and deployed in Kudu. When a change is pushed to a Cloud Environment, the Kudu deployment is started. CI/CD is also utilizing this flow.

The Project History page offers information on CI/CD flow deployments. Navigate to the deployment and inspect the Deployment Kudu Log for insights.

How to resolve the issue

Below is a list of different options for fixing the issue:

• Ensure your code can compile and run (relevant only if you have enabled the skipBuildAndRestore toggle in V2).

• For a project running Umbraco 15 or later, make sure the CompressionEnabled setting is set to false.

  • The static assets compression operation on the app service is resource-intensive and slows down the Kudu deployment.

• Running npm commands via .csproj files is generally unsupported on Umbraco Cloud.

• Create and commit a small change and try deploying again.

  • A small change can be adding a dummy text file next to your code files or adding a comment in a .cs file.

• Make sure your artifact is following the best practice.

Environment errors after deployment

Unable to determine environment by its {environment-id}

This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message:

“System.InvalidOperationException: Unable to determine environment by its {environment-id}”

This issue arises because the environment is missing in the local umbraco-cloud.json file.

How to resolve the issue

To resolve this issue, follow these steps:

1. Navigate to Kudu in your Live environment.

2. Select “Debug console” and choose “CMD”.

3. Find the umbraco-cloud.json file. The path to this file may vary depending on your setup, but the default location on the cloud is C:\home\site\repository\src\UmbracoProject.

4. Click ‘edit’ on the file and copy all its content. This content is consistent across environments, so it’s safe to do so.

5. Paste the copied content into the umbraco-cloud.json file in your local project and push the changes.

After completing these steps, your left-most mainline environment should be correctly registered across all environments, allowing you to continue your work without any issues.