Why has the public ID of my asset changed?

In Cloudinary, the public ID is a critical part of an asset's delivery URL. It uniquely identifies an asset (image, video, or raw file) within your Cloudinary account, and forms part of the delivery URL. Therefore, when the Public ID changes, the URL associated with the asset changes as well.

Under normal conditions, public IDs remain consistent. However, there are scenarios in which an asset's public ID may change

Common reasons for public ID changes

1. Asset movement (via UI or API) 
   Moving assets from one folder to another using the Media Library or through the API, will alter the public ID. 

   • Example: Moving an asset from /old-folder/image to /new-folder/image would result in a new public ID based on the new folder path.

   • Implication: Moving assets can disrupt delivery paths unless all references to the asset are updated to use the new Public ID.

   • For further reading, please see How to move an asset from one folder to another 

2. Renaming an asset (via UI or API)
   Renaming an asset, whether done via the Media Library or the API, changes the asset's Public ID.

   • Example: Renaming an image from image to product will cause the public ID to change accordingly, from something like /folder/image to /folder/product.

   • Implication: Similar to asset movement, all references to the old public ID need to be updated to reflect the new name, or delivery of that asset will break.

Other reasons for public ID changes

• Duplicate file prevention and unique filename Setting
  If the unique filename feature is enabled (Cloudinary’s option to automatically assign a unique identifier to avoid file overwriting), a string of unique characters will be appended to the public ID upon asset upload.

  • Example: Uploading product.jpg twice with unique filename generation enabled could result in the public IDs /folder/product_vr3abc and /folder/product_yu3zbc.

  • Implication: The asset will have a different public ID each time it's uploaded, which could result in unexpected URLs.

Best practices for managing public ID changes

1. Avoid unnecessary asset movement
   If possible, plan folder structures in advance to minimize the need to move assets, which will result in public ID changes.

2. Use descriptive public IDs
   When renaming or uploading assets, use descriptive and meaningful public IDs. This practice can help avoid confusion when accessing or updating assets.

3. Track public ID changes
   Set up an internal system or process to log any changes to public IDs. This ensures that everyone in your organisation is aware of updates and can make necessary changes to references. One way to do this is to make use of webhook notifications.

4. Cautious use of unique filenames
   If unique filenames are necessary, ensure that the naming conventions for public IDs remain predictable and documented for ease of use.

5. Update references promptly
   Whenever a public ID change occurs, update all references to that asset in your websites, apps, and documentation immediately.

Further reading

It's important to note that some existing accounts, and all Cloudinary accounts created after June 4th 2024 will use dynamic folder mode. This decouples the identifier used by an asset when being stored or managed in the Media Library (referred to as the display name) from the identifier used when being delivered (public ID).

The Folder modes section of our documentation goes into more detail should you wish to learn more.