Umbraco Cloud
CMSHeartcoreDXPMarketplace
  • What is Umbraco Cloud?
  • Frequently asked questions
  • Security
    • Web Application Firewall
  • Sustainability Best Practices
  • Getting Started
    • Explore Umbraco Cloud
    • The Cloud Portal
      • Organizations
      • Sustainability Dashboard
    • Project Overview
    • Environments
    • Flexible Environments (beta)
    • Baselines
      • Baseline Merge Conflicts
      • Break Reference between Baseline and Child Project
      • Handling configuration files
      • Pushing Upgrades to a Child Project
    • Plans
    • Migrate to Umbraco Cloud
    • Repositories in a Cloud Project
    • Best Practice for Working in Teams
    • Migrate between regions
  • Set up
    • Ready to Set Up Your Project?
    • Working with a Local Clone
      • Legacy Umbraco Visual Studio Setup
    • Manage Environments
    • Project Settings
      • Managing Transport Security
      • CDN Caching and Optimizations
      • Dedicated Resources
      • Upgrade your Plan
      • Public Access
      • Managing Hostnames
        • New Certificate Authority for custom hostnames
        • Rewrite rules
        • Custom Certificates
      • Management API Security
      • Umbraco CI/CD Flow
        • Cloud API For CI/CD Flow
        • Configuring a CI/CD pipeline
          • Azure DevOps
          • GitHub Actions
        • Troubleshooting
        • Known Limitations and Considerations
      • External Services
      • Usage
        • Bandwidth
      • Availability and Performance
      • Team Members
        • Technical Contact
      • Secrets Management
      • Project History
    • Private NuGet Feed on Umbraco Cloud
    • Going Live
    • Media
    • External Login Providers
    • Azure Blob Storage
      • Connect to Azure Storage Explorer to upload files manually
      • Connect and Upload Files Programmatically to Azure Blob Storage
    • Users
    • Multi-Factor Authentication
    • Application Insights
    • Config Transforms
    • SMTP Settings
    • Payments
      • Subscription migration information and FAQ
    • Power Tools (Kudu)
      • View the Files on your Cloud Environments
      • Generate UDA files
      • Manually run Extractions on your Cloud Environments
  • Deployments
    • Deployment
    • Deploying between environments
    • Transferring Content, Media, Members, and Forms
    • Deploying Deletions
    • Deployment Webhook
    • Deploying Changes
    • Umbraco Forms on Cloud
    • Deploy Dashboard
    • Hotfixes
      • Apply hotfix by manually moving files
      • Apply hotfix by using Git
    • Restoring Content
      • Partial Restores
  • Databases
    • Keep Your Data Secure and Accessible
    • Working with databases
    • Database backups
    • Database
      • Connecting to the Database on Mac
    • Working with a Cloud database locally
  • Product Upgrades
    • Stay Up to Date with Umbraco Cloud
    • Product Upgrades
    • Major Upgrades
    • Minor Upgrades
    • Version Specific Upgrades
      • Migrate from Umbraco 8 to the latest version
      • Migrate from Umbraco 7 to Umbraco 8 on Umbraco Cloud
    • Upgrade your projects manually
      • Manual upgrade of Umbraco CMS
      • Manual upgrade of Umbraco Deploy
    • Dependencies on Umbraco Cloud
  • Troubleshooting
    • Resolve Issues Quickly and Efficiently
    • Troubleshooting FAQ
    • Log files
    • The Umbraco Backoffice
    • The Frontend
    • The Umbraco Cloud Portal
    • Site Performance checklist
    • Troubleshooting deployments
      • Extraction error: Config transforms failing
      • Extraction error: Data Type collisions
      • Dependency Exception
      • Merge Conflicts on Flexible Environments
      • Troubleshooting deployments failing with no error message
      • Troubleshooting duplicate dictionary items
      • Troubleshooting language mismatches
      • Path too long Exception
      • Schema Mismatches
      • How to resolve collision errors
      • Extraction error: "Type not found! "
    • Cloud Errors
  • Release Notes
    • Overview 2025
      • April 2025
      • March 2025
      • February 2025
      • January 2025
    • Overview 2024
      • December 2024
      • November 2024
      • October 2024
      • September 2024
      • August 2024
      • July 2024
      • May 2024
      • April 2024
      • March 2024
      • February 2024
      • January 2024
    • Overview 2023
      • December 2023
      • October 2023
      • September 2023
      • August 2023
      • June 2023
      • May 2023
      • April 2023
      • March 2023
      • February 2023
      • January 2023
    • Overview 2022
      • December 2022
      • November 2022
      • September 2022
      • August 2022
      • June 2022
      • May 2022
      • April 2022
      • March 2022
      • February 2022
      • January 2022
Powered by GitBook
On this page
  • Cause
  • Identify the issue
  • Fixing
  • Important Notes

Was this helpful?

Edit on GitHub
Export as PDF
  1. Troubleshooting
  2. Troubleshooting deployments

Troubleshooting duplicate dictionary items

PreviousTroubleshooting deployments failing with no error messageNextTroubleshooting language mismatches

Last updated 1 year ago

Was this helpful?

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.

Cause

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.

Identify the issue

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:

Some artifacts collide on unique identifiers.
This means that they have different Udis, yet
they refer to the same unique Umbraco object
and therefore cannot be processed.
---------------------------------------------
Collisions for entity type "dictionary-item":
    Collisions for unique identifier "Welcome":
        UdaFile: ~/data/revision/dictionary-item__0cff5cd8fca24b9a80d29390dfb917af.uda
        UdaFile: ~/data/revision/dictionary-item__1f1d9fe32e094e6c9b3c8871e123e34c.uda

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:

Some artifacts collide on unique identifiers.
This means that they have different Udis, yet
they refer to the same unique Umbraco object
and therefore cannot be processed.
---------------------------------------------
Collisions for entity type "dictionary-item":
    Collisions for unique identifier "Welcome":
        Artifact: umb://dictionary-item/01aaeeed662645c8b348b2aa5ff83d6d
        {DictionaryItem umb://dictionary-item/fe1cae45094b43fba0545bdc45d121ed}

Fixing

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:

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

  2. Ensure you remove all duplicate entries in the backoffice if any.

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

  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.

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

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

  1. Repeat steps 5-6 if there are any other environments.

Important Notes

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.

You can find more details about UDA files in this article:

Generating UDA files