Cloudinary provides several methods to help you understand why a request to deliver an image or video asset failed, including debugging specific URLs, all URLs included on a webpage, and details of errors that occur for any asset in your account.

X-Cld-Error header

There are multiple cases which can cause an asset not to appear, and in addition to using standard HTTP status codes to indicate common error reasons, Cloudinary sends a custom HTTP header to provide Cloudinary-specific information about the reason for the failure.

This header is called x-cld-error, and you can see the value by checking the HTTP response headers sent when your browser tried to load the asset's delivery URL.

Accessing the x-cld-error header with browser debug tools

The precise instructions may differ slightly between browsers, but if you open your browser's Developer Tools and view the Network tab, you can see the request and response headers for HTTP requests made by your browser when loading the current webpage. 

You may need to refresh the page to see the requests in the Network tab, as it may not record the requests made before you opened the Developer Tools section.

If you've opened an image URL directly in a new tab or a new window, you may also need to click the "preserve log" option before refreshing, so that when the browser shows an error message in that tab, the developer tools aren't showing you just error page's details but also the earlier request for the image or video file.

In the network tab, if you click a specific request, you can see the request and response headers including the X-Cld-Error header with the specific error message.

Cloudinary Media Inspector

Cloudinary has released a debugging extension for use with the Google Chrome web browser, and you can find it in the Chrome Web Store: https://chrome.google.com/webstore/detail/cloudinary-media-inspecto/ehnkhkglbafecknplfmjklnnjimokpkg

The Media Inspector tool shows you a summary of all media assets loaded on the current page, and where the asset was loaded from Cloudinary, it also shows details of the transformations options used, and if the request was an error, details about the reason for that error, taken from the x-cld-error HTTP header mentioned above.

For example debugging a successful request for an original media asset with no transformations applied produces the following result:

And debugging a request which failed because the Transformation parameters in the URL were invalid shows the reason for the error with both the HTTP status code, and the x-cld-error HTTP header:

Error reports

On paid Cloudinary plans, your account's reports section includes details of errors that occurred when Cloudinary received requests to deliver assets from your account.

The Error reports section shows the most common HTTP error codes, and provides a summary of the specific errors, including the exact URLs that were requested to cause the error, and the HTTP Referer value, if it was provided to us.