# Troubleshooting
## 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, you need to ensure that when the site is restoring on Umbraco Cloud it is not using the lock file. You can do this by adding this line in your csproj file:
```xml
>true
```
[Force Evaluate option on dotnet restore](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-restore#options)
### 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](/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbraco-cloud-api.md#get-deployment-diff) responds with status 409 and the following JSON payload:
```json
{
"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-github)
* [How to skip cloud-sync in Azure DevOps](#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}](#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:
```sh
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](/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/deployment.md).
#### 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](#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:
5. 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.
6. 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
7. 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](#skip-cloud-sync-in-github) section.
1. Navigate to your `azure-release-pipeline.yaml` and comment out these two lines:
```sh
dependsOn: cloudSyncStage
condition: in(dependencies.cloudSyncStage.result, 'Succeeded', 'Skipped')
```
2. Ensure that your Azure DevOps repository is up to date with any changes in your Umbraco Cloud environment.
3. Find the pipeline in Azure DevOps.
4. Click on "Run Pipeline" in the top right corner.
5. Click on "Stages to run."
6. Uncheck the "Umbraco Cloud Sync" checkbox.
7. Confirm on "Use selected stages".
8. 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](/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md) or [Azure DevOps](/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md) 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:
```none
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 `.csproj`file 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](/umbraco-cloud/optimize-and-maintain-your-site/monitor-and-troubleshoot/power-tools.md) 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](/umbraco-cloud/optimize-and-maintain-your-site/monitor-and-troubleshoot/project-history.md) 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](/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/artifact-best-practice.md).
## 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:
```none
“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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.umbraco.com/umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.