What Are the Common Error Codes Returned in the x-cld-error Header When Delivering Assets?

Here is a reference guide designed to help users troubleshoot and resolve common errors encountered when using Cloudinary's services. This knowledge base lists and explains various x-cld-error codes returned by Cloudinary, providing descriptions of each error's cause and recommended solutions. For more information on debugging these errors, please refer to the article: "Debugging Why an Image or Video Doesn't Load in Your Application or Site."

For further details or complex issues, it is recommended to refer to the official Cloudinary documentation or contact Cloudinary support.

Resource not found - <public_id>

• Cause: The requested resource does not exist, possibly due to an incorrect public_id or deletion of the file.
• Possible Solution:
  • Double-check the public_id to ensure it is correct, and verify that the resource has not been deleted or moved.
  • Confirm that you are requesting the appropriate resource type and delivery type in the URL. For example, check if the URL specifies the correct resource type and delivery type, such as image/upload, image/private, video/upload, or other valid types supported by Cloudinary. Ensuring these elements are accurately specified will help prevent errors related to resource retrieval.

Resource not found (public_id is not specified in the error message)

• Cause: This indicates that an error occurred, but the specific cause is hidden due to account security settings.
• Next Steps:
  • The underlying message can be seen in the Error report for paid plans.
  • You can also reach out to the support team to verify the exact error or adjust the settings to reveal the underlying issue.

Unknown or invalid referenced image <public_id> of type upload

• Cause: The referenced image could not be located.
• Possible Solution:
  • Double-check that the public_id is correct and ensure the resource has not been deleted or moved. It's important to ensure that all asset references in your request are accurate and that the assets still exist in their expected locations.
  • If the public_id of an image contains slashes (e.g., animals/dog), you should replace the slashes with colons when using that image as an overlay (e.g., the overlay image should be animals:dog).

Error in loading - <remote source URL>

• Cause: This error means that Cloudinary is unable to retrieve the requested asset when using the fetch delivery type. This issue could arise for several reasons, such as network connectivity problems or access restrictions on the file's location. The asset might also be hosted on an external server that is temporarily down or unreachable.
• Possible Solution:
  • To resolve this issue, ensure that the asset's URL is correct.
  • Check the remote server to verify that it is operational and that the asset is accessible by Cloudinary.
  • It would help if you also looked for any network issues that might be affecting the connection between Cloudinary and the server hosting the asset.

Invalid Transformation

• Cause: The transformation key or value specified does not exist or is invalid. Additionally, it is possible that the URL format is incorrect or improperly structured.
• Possible Solution:
  • Ensure that the key or value matches the expected format and that the URL is properly formatted according to standard conventions.

Auto gravity can only be used with crop, fill, lfill, fill_pad or thumb

• Cause: Attempting to use the g_auto (auto gravity) parameter with a crop/resize mode that does not involve cropping, such as scale or fit, will result in an error.
• Possible Solution:
  • Ensure that the g_auto parameter is used with a compatible cropping mode, such as crop, fill, lfill, fill_pad, or thumb.
  • If you are using g_auto with an unsupported mode, like scale or fit, either change to a supported mode or remove the g_auto parameter from your transformation.

Can't generate images using add-ons if URL is not signed

• Cause: Trying to use a Cloudinary add-on feature with an unsigned URL when the feature requires a signed URL.
• Possible Solution:
  • Deliver URLs that use the add-on by using a signed URL or by generating them eagerly.
  • There is also an option to remove this requirement by selecting the add-on in the "Allow unsigned add-on transformations" section on the Security page in the Console Settings.

deny or ACL failure

• Cause: There are several possible reasons for this error. It might be due to the ACL settings in your cloud configuration, an issue with the token if you're using token-based authentication or restrictions on PDF and archive files for free accounts.
• Possible Solution:
  • Review your request (Country Code, IP, Path, Content-type, Referrer, User-Agent), as it could be restricted due to the ACL settings you have requested to configure.
  • If you are using token-based authentication, ensure that the token is valid, correctly formatted, not expired, and properly signed.
  • If you are on a free Cloudinary account and delivering PDFs or archive files, please refer to the article "PDF or ZIP files appearing in Media Library, but download URLs return an error." If you have checked all of the above and are still facing issues, please contact Cloudinary support for further assistance.

public_id is too long

• Cause: When using 'fetch' to deliver remote images, the origin image's URL serves as the public ID of the new resource. The maximum length for a resource's public ID is 255 characters (though this limit can be extended in certain cases). If a URL exceeds this limit, the fetch request will fail.
• Possible Solution:
  • For URLs exceeding the limit, you can use our API to upload the image from its remote location or set up an upload-mapping from its origin.
  • Alternatively, you can contact Cloudinary support to check if the character limit can be increased for your account.

Video is too large to process synchronously, please use an eager transformation with eager_async=true to resolve

• Cause: This error is due to Cloudinary's video transformation size limits: 40MB for Free plans and 300MB for paid plans. These limits do not apply to the size of videos you can upload but to on-the-fly transformations or eager transformations that are not processed asynchronously. The limit exists because larger videos take more time to transform, potentially causing delays or timeouts.
• Possible Solution:
  • To manage this, transformations should be performed eagerly (in advance) and processed asynchronously in the background, allowing you to work with videos up to your account's maximum size.
  • Eager transformations can be requested during upload, set in an upload preset, or executed via the explicit method for existing videos, or when using the "fetch" feature to load a new asset from a remote URL.
  • Make sure to include the eager_async=true parameter to process the request asynchronously.
  • If your application needs to be notified when the video is ready, use the 'eager_notification_url' parameter to alert your server once the transformation is complete. The video will then be accessible at its usual URL.

To understand why your assets are returning a 40X error, please check out this article: "Why Is My Asset Returning a 40X Error?"