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 a 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

• Fixed folder mode only -- Asset movement (via UI or API) If your product environment uses the legacy fixed folder mode, then moving assets from one folder to another using the Media Library or through the API alters the public ID.

  • Example: Moving an asset that has the public ID old-folder/my-imagefrom /old-folder to /new-folder would result in automatically renaming the asset to new-folder/my-image based on the new folder path.
  • Implication: Moving assets from one folder to another can disrupt delivery paths unless you also update all references to the asset in your code to use the new Public ID.

• Directly renaming a public ID (via UI or API) Renaming an asset's public ID, whether done via the Media Library or the API (/rename method), changes the asset's Public ID.

  • Example: Renaming an image's public ID from image to product causes the public ID to change accordingly, from something like /folder/image to /folder/product.
  • Implication: If you rename a public ID, make sure to update all references to the old public ID in your code to reflect the new name. Otherwise, delivery of that asset breaks.
  Note

  If your product environment uses the dynamic folder mode, you can freely rename the asset's Display name (which is the primary name displayed in the Media Library) without affecting the public ID.
  

Other reasons for public ID changes

• Duplicate file prevention and unique filename Setting If you enable the unique filename feature (Cloudinary's option to automatically assign a unique identifier to avoid file overwriting), Cloudinary appends a string of unique characters 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: Each upload assigns a different public ID to the asset, resulting in unexpected URLs.

Best practices for managing public ID changes

• On fixed folder mode environments, avoid unnecessary asset movement If possible, plan folder structures in advance to minimize the need to move assets, which results in public ID changes. Alternatively, contact customer support to request migration of your product environment to dynamic folder mode, which enables you to freely move assets between folders without affecting the public ID.

• Use descriptive public IDs When renaming or uploading assets, use descriptive and meaningful public IDs. (or take advantage of the use_filename parameter to automatically use the filename as the public ID). This practice can help avoid confusion when accessing or updating assets.

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

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