What are the common error codes returned in the x-cld-error header when delivering assets?

This article 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, check out the Diagnosing error codes video tutorial.

For further details or for help solving complex issues, you can contact Cloudinary support.

Resource not found - <public_id>

• Cause: The requested resource doesn't exist, possibly due to an incorrect public_id or deletion of the file.
• Possible Solution:
  • Double-check the public_id to ensure it's correct, and verify that the resource still exists.
  • 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 helps prevent errors related to resource retrieval.

Resource not found (public_id isn't specified in the error message)

• Cause: This indicates that an error occurred, but account security settings hide the specific cause.
• Next Steps:
  • The Error report shows the underlying message 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: Cloudinary can't find the referenced image.
• Possible Solution:
  • Double-check that the public_id is correct and ensure the resource still exists. 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 reside on an external server that's 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's 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 doesn't exist or is invalid. Additionally, it's 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.

Use auto gravity only with crop, fill, lfill, fill_pad or thumb

• Cause: Attempting to use the g_auto (auto gravity) parameter with a crop/resize mode that doesn't involve cropping, such as scale or fit, results in an error.
• Possible Solution:
  • Ensure that you use the g_auto parameter 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 isn't 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 the ACL settings you configured could restrict it.
  • If you're 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, refer to the note in the Media delivery guide. If you 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 Cloudinary can extend this limit in certain cases). If a URL exceeds this limit, the fetch request fails.
• 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 they can increase the character limit 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 don't apply to the size of videos you can upload but to on-the-fly transformations or eager transformations that aren't processed asynchronously. The limit exists because larger videos take more time to transform, potentially causing delays or timeouts.
• Possible Solution:
  • To manage this, perform transformations eagerly (in advance) and process them asynchronously in the background, allowing you to work with videos up to your account's maximum size.
  • You can request eager transformations during upload, set them in an upload preset, or execute them 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 notification when the video is ready, use the 'eager_notification_url' parameter to alert your server once the transformation is complete. The video then becomes accessible at its usual URL.