Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
When creating a new environment on your Umbraco Cloud project, you might encounter some issues regarding some of the default data types built into Umbraco. The data types in question are:
Content Picker
Media Picker
Member picker
Multiple Media Picker (using Media Picker)
Related Links
Since these 5 data types are part of the Umbraco CMS, these will be created by default on each new environment on Umbraco Cloud. If metadata files/structure files for these data types have been generated on your Live environment, you might run into extraction errors on your newly created Development or Staging environment. New environments will be exact clones of the Live environment, thus containing all structure and metadata files from that environment.
The issue will present itself as an extraction error on your Development or Staging environment once you've created them.
Open the error message by clicking More info.
In the case illustrated above, there are four data types and each has two UDA files.
What this means is that a file has been generated for each data type on both the Live and the Development environment. The Umbraco Deploy engine needs to create one instance of each data type but is currently not able to do so, since it doesn't know which files to build the data types based on.
See the steps below on how to resolve the issue.
Access the backoffice of the affected environment (Development or Staging)
Find the Data Types folder in the Developer section
Delete only the data types mentioned in the error message
In the case above, I would need to delete Member Picker, Multiple Media Picker, Related Links, and Content Picker
Access Kudu for the affected environment
Follow the Kudu Documentation to run an extraction on the environment
When you get a deploy-complete marker, the issue has been resolved!
When you've followed these steps, go through your Development / Staging environment and make sure everything has been created as expected.
The final step you need to take before your Development / Staging environment is completely in sync with your Live environment is to restore the content.
Deleting a content node that references a deleted content node, will give you the following error when trying to transfer the node:
The error indicates that on the Home page, a picker, for example, refers to another content item. This other content item has either been deleted or is in the recycle bin in the environment you're deploying from.
If you try and delete a node that references another one, you will be warned in the backoffice that it has a reference and you might encounter issues if you delete it:
To resolve the issue, find the Contact page (hint: the nodeId can be used in the search field in the top-right of the backoffice) and publish it again. This should remove the reference to the node that is no longer available. Transferring the Contact page node should now succeed.
This error might pop up if your project's files were recently upgraded/updated to the latest version. Any deployment you try will end up failing instantly.
This error is caused by leftover upgrade markers interfering with the Deploy process. This might happen if your environment was restarted during the upgrade, or the upgrade process encountered some issues.
In order to fix this issue, you would need to use KUDU to remove the leftover marker files.
Access KUDU on the source environment (the one you are deploying from)
Navigate to site > locks folder
In the folder, there should be a file named upgrading, upgrade-failed or failed-upgrade. Remove these files.
Repeat the operation on the target environment - it might also have the leftover marker
Once the leftover marker files are removed, your deployments should go through without problems.
When transferring or restoring content between two Umbraco Cloud environments, you might run into Schema mismatch errors. These usually occur when the schema isn't in sync between the source environment and the target environment. Schema refers to Document Types, Media Types, Data Types, Templates, and Dictionary items)
In this article, you can learn how to resolve schema mismatch issues and how you can avoid them in the future.
When you run into schema mismatch errors, they will usually look something like this:
In this error message, you can see exactly which schema mismatch(es) is preventing the content transfer/restore.
To resolve this error, check for pending deployments on the source environments. If you are working locally, push any changes that have not been committed through Git. If you are transferring between two Umbraco Cloud environments, you can see and deploy pending changes through the Umbraco Cloud Portal.
If there are no pending deployments in your source environment, there are two ways to go about resolving the schema mismatch:
Make a minor change to the schema with mismatches in the source environment (in the example above it would be the Contact Us document type).
Deploy the change to the next environment
This will update your schema in the target environment and ensure it is in sync with the source environment
If the mismatches involve differences in the aliases or names, changing these manually on the target environment will enable you to transfer your content.
Issues with deployments on Umbraco Cloud often come down to a misunderstanding on how to work with Umbraco Cloud. It is important to always work left to right as mentioned in the Deployment section.
There are two ways to deploy on Umbraco Cloud, a deployment that transfers content and media:
A Deployment that transfers structure files (doc types, data types, templates, dll's, etc.)
There are some common errors associated with both of these. Most of the time it is caused by conflicting UDA files between the two environments you are deploying between.
The most common Deployment issues are listed below with guides on how to fix them:
The most common Content Transfer / Restore issues are listed below:
If you are using dictionary items on a multi-lingual setup, you might see errors related to mismatches between languages.
This error occurs when a language is deleted from the backoffice after you have defined some dictionary items. When creating a new site, or a new environment on a project, said instance will investigate the dictionary items' UDAs and find that they mention a language that is not present in the backoffice anymore.
The issue will show up as an extraction error on your Umbraco Cloud environment with a red indicator.
Upon closer inspection, a more detailed error will reveal itself: Languages in source and destination site do not match.
This error can occur in two scenarios and is caused by deleting any backoffice language while having dictionary items present on your project.
If the below conditions are met on the "source" environment, you will be presented with the 'Languages in source and destination site do not match.' error on the newly created instance:
You have at least two languages set in the backoffice
You defined some dictionary items and fill out the translations
You removed one of the languages via the Settings dashboard after defining the dictionary items
The first scenario (Scenario 1) is when you add a new environment to your project (in most cases it would be the Development environment, though it could happen with Staging as well).
The second scenario (Scenario 2) is when you create a new project from a baseline, where the baseline would be your project with dictionary items.
There are 2 ways to get this error resolved.
Method 1 - prevention is better than cure! If you resave all your dictionary items on the source environment after deleting the backoffice language(s), the newly created Development environment/child project will have no issues whatsoever.
Method 2 - if you have already created the new instance and do not wish to re-create it, you could instead follow this flow: Navigate to site/wwwroot/data/revision folder via KUDU tools, find the dictionary items, and then edit the UDA files directly.
Deleting the section responsible for the removed language and saving the file should clear out the error - as long as you run a manual extraction afterward. Manually re-saving the dictionary items in the backoffice after the extraction is greatly recommended - it will log those changes in the git repository, and will correct said dictionary items on the source environment with the next deployment.
This issue will present itself as an extraction error on your target environment for a deploy.
The extraction error happens with two Document Types where one of them have been allowed as a child node type for the other Document Type.
If the Document Type that has been allowed as the child is then deleted, the references for the child Document Type are not removed from the parent Document Type.
Because the parent Document Type still has the references from the deleted child Document Type, the environment will throw an extraction error when trying to deploy to the next environment. The error will tell us that it can not find the Document Type that is allowed as a child.
Open the More info to see the details for the error message.
In the case illustrated above the extraction error is saying:
To resolve the extraction error go to the backoffice of the environment, which you are deploying from and find the Document Type that is listed as the parent for the deleted Document Type in the error message.
In this case that is the Document Type "test1".
Resave the parent Document Type so that the references to the deleted child Document Type will be removed from the parent Document Type.
After the Document Type has been saved again make a new deploy and you will see that the deploy will go through.
The environment will be green and the deployment has successfully gone through without any errors.
Sometimes you might notice that even though your deployments are coming through without errors, no changes are being applied to the Cloud environments. This might be due to Config Transforms failing during the extraction process.
This issue may occur if you have added custom to your project.
Since Config Transforms are applied on every data extraction, the behavior will continue until the Config Transform files are either corrected or removed.
This problem is a bit tricky to spot, as the only indicator is that changes you made on the source environment are not being applied - even though the deployment was complete (although when pushing from local you might get a warning message).
The environment overview on your project will most likely not mention anything, which means you will have to delve into KUDU.
Access on the environment where you expected to see your changes reflected
Navigate to site > deployments folder in KUDU
Find the latest deployment folder, either by date or by ID of the deployment (you can find the latest active deployment ID by opening the active file in the folder)
If the deployment folder with the latest ID contains only two items (log.log and status.xml), that means something went wrong as we would normally see two more files - commits.uc and manifest
Open the log.log file and look for anything mentioning XmlTransform.
An example of a faulty config transform not being applied could look something like this:
Verify the Config Transform file mentioned in the error message and ensure the XML is valid.
Update the Config Transform file as necessary on your local solution and deploy the change to the Cloud environments.
To find errors in the config transform, you can use an xml validation tool like https://www.xmlvalidation.com/
Run a to extract the schema that you previously deployed.
When you have Media files on your Umbraco Cloud project with a file name longer than 80 characters, you will not be able to transfer and/or restore between your Cloud environments.
The exception you will see on content transfer / restore will look something like this:
System.IO.PathTooLongException: The specified path, file name, or both are too long. The fully qualified file name must be less than 260 characters, and the directory name must be less than 248 characters.
The full stacktrace:
This is a known issue with Microsoft servers, that limits the amounts of characters allowed in a path.
In order to fix this error, you will need to connect to the Live Environments project's database.
Connect to your Live environments database.
In the database run the following query to find the faulty media files:
Find the files in the Media section in the Umbraco backoffice.
Remove the media files from the backoffice.
Make sure to note down where the media item is being used in the content
Change the names of the media files giving them a name shorter than 80 characters.
Re-upload the renamed file to the Media section in the backoffice.
Once re-added in the backoffice, make sure to add the media back in the content where it was used.
This guide is for solving collision errors on your Umbraco Cloud project. Use this guide when you encounter an error like this:
The error means that two (or more) .uda files have been created for the same entity. The .uda files contain schema data for each of your entities e.g Document Types, Templates, Macros, Dictionary Items, Data types, etc (for a full list of these entities see What are UDA files?).
In this example, there are two .uda files that share the same alias which leads to a conflict: it is impossible for Deploy to know which of the files to use, so it gives up and sends an error back.
Does the collision error involve Dictionary items? Use this guide instead: Troubleshooting duplicate dictionary items
You can run into an error like this on all of your Cloud environments. Sometimes you might also run into it, on a local clone of your project. This guide will use an example, where two files are colliding on a Development and a Live environment.
When you have two or more Cloud environments, we recommend that you never create or make schema changes directly on the Live or Staging environments. You should work with schema only in your Development environment or even better, your local clone of the project.
In the example above the entity involved is a Document Type with "home" as the alias. There are two colliding files both located in the /deploy/revision folder. The files are colliding because they share the same alias but have different GUIDs (also the name of the files).
In order to fix this problem, you will have to decide which of the colliding entities is the correct one and the one you want to use on your Live environment.
Let's use the example from the beginning of this article, where two .uda files for the Document Type "home" are colliding.
For this example, it’s decided that the Document Type currently used on the Live environment is the one we want to use going forward.
In order to figure out which of the two colliding .uda files are the one for the Document Type being used on the Live environment follow these steps:
Connect to the database of the Live environment using the connect to your cloud database locally tutorial
Run one of the following queries on the database, depending on the type you see the error with
Run the following query, if the error states that the error is a Collisions for entity type "document-type":
Run the following query, if the error states that the error is a Collisions for entity type "template":
Run the following query, if the error states that the error is a Collisions for entity type "macro":
Run the following query, if the error states that the error is a Collisions for entity type "data-type":
The above-mentioned queries will give you the udi of the entity in use on the live environment.
You now know which .uda file you want.
We strongly recommend that you resolve this locally since this will ensure that the changes you make are added to your Git repositories. Otherwise, you may end up having the same problem next time you deploy.
Clone down the Development environment to your local machine
Run the project locally and verify that you get the same extraction error as on your Cloud environments (HINT: look for a deploy-failed marker in your local /deploy folder)
When you run the project, you should see an error message in the browser once the site starts to build
Remove the wrong .uda file (It's the one we did not find in the live environment just before) from the /deploy/revision folder - you will not be able to see the Document Type in the backoffice because of the failed extraction.
Open the Umbraco Backoffice and go to Settings -> Deploy to see the Deploy dashboard.
Select Schema deployment from data files in the dropdown.
You will now see a deploy-complete marker in your local /deploy folder
Does the error mention Templates? You might experience that .uda files for a template are colliding. When this is the case, we recommend that you copy the content of the cshtml file associated with the template you want to keep on your project - this way you'll have a backup of the code you want to use.
Before pushing the changes to the Development environment, you need to access the backoffice of the Development environment and remove the Document Type from there.
Commit and push the changes from your local clone to the Development environment, using your local Git client.
When the push from local to the Development environment has been completed, refresh the Umbraco Cloud portal and you will see that the Development environment is now green, which means that the extraction error has been resolved.
Sometimes you might need to run another schema deployment on your Cloud environment after deploying to turn your environment green. To do this, follow the steps described in the schema deployment guide.
The final step is to deploy the pending changes from Development to your Live environment, to ensure everything is completely in sync.
Has your Umbraco Cloud project been using Courier in the past and have you been deploying dictionary items between your environments? Then you may see errors and/or duplicated dictionary items when your site is upgraded to Umbraco Deploy.
Due to how Umbraco Courier has been handling dictionary items in the past, old sites having used Courier to transfer these - are currently very likely to see errors when trying to use Umbraco Deploy with these items.
Courier handled dictionary items only using their ItemKey (alias) and did not take into account that dictionary items also carried a unique identifier. Since this unique identifier was not known or handled by Courier - it would not be carried over to other environments when these dictionary items were deployed. As Courier never cared about or used this unique identifier - everything seemed to be in order most of the time.
Upgrading to Deploy, one of the major improvements is that Deploy handles everything by its unique identifier making it much more stable. However when dictionary items are in a state of not having consistent unique identifiers across each individual environment - they will not work with Deploy unless they are synchronized.
The issue will show up as an extraction error on your Umbraco Cloud environment with a red indicator.
There are two types of duplicate dictionary item errors. The first scenario (Scenario 1) is when you have duplicate UDA files for each of your dictionary items. When this is the case, you will see an error message like this:
The second scenario (Scenario 2) is when you do not have duplicate files for your dictionary items. In this scenario, you will have one UDA file for each of your dictionary items, but each of them are referenced with a different ID in the database. In this scenario you will see an error message like this:
You can find more details about UDA files in this article: Generating UDA files
In order to fix this issue, it is required that all dictionary items are aligned to have the same unique identifier for a specific ItemKey across all environments. The easiest way of doing this is to select an environment where you believe all your dictionary items are mostly correct, remove any duplicated items, and then ensure that the changes are pushed to your other environments:
Ensure you do not have any duplicated dictionary items in your UDA files. If you do - these will need to be cleaned up as a first step.
Ensure you remove all duplicate entries in the backoffice if any.
When you can successfully create a deploy marker and get a deploy-complete in your /data/ folder - your environment should be "clean" and you are good to go.
If you are encountering Scenario 2, you might not be able to get a deploy-complete marker. Instead, you need to verify that you do not have any duplicate UDA files in your /data/revisions folder or dictionary item entries in the backoffice, and then move on to step 4.
Create a deploy-repairdictionaryids marker in the /data/ folder. Do this by typing echo > deploy-repairdictionaryids in CMD console in Kudu.
The command will not work on your local clone. If you've done the clean-up from steps 1 and 2 on your local machine, you will need to commit and push these changes to your Cloud environment, and run the command there
Doing this will make Deploy run through all of the dictionary items in the database and remove any duplicates (there should be none, if you did the manual cleanup correctly).
When done with this, it will go through all UDA files and check if there is any duplicates existing in your site for that particular ItemKey used in that UDA file. If it finds a duplicate - it will update the ID to match, so your dictionary item is synchronized with the UDA file.
When this is done - and you end up with a deploy-complete marker - you will need to transfer your dictionary item UDA files to the next environment, to ensure the same IDs will be applied here.
Create a deploy-repairdictionaryids marker in the /data/ folder.
Deploy will now again delete any existing duplicate entries and update the IDs of the remaining entries to match the IDs in the UDA files.
Repeat steps 5-6 if there are any other environments.
What Deploy will not help you with, is duplicated items that do not have a corresponding UDA file. Deploy does not know what to do with a dictionary item that doesn't have a matching UDA file. If Deploy finds duplicates with no UDA files, one of them will be removed to ensure there are no duplicate errors. For this item to be deployed, you will need to recreate a UDA file for it - this can be done by saving the item through the backoffice.
Once you've cleaned up the dictionary items on your Umbraco Cloud environments, it is important that you clone down a fresh clone of your project locally to ensure you have all the correct / updated files on your local machine.
