Why am I getting an error when trying to fetch an image from a remote URL?

X-Cld-Error header for general debugging

When experiencing an error accessing an asset's URL, you can check the X-Cld-Error HTTP response header to get more details about the error. This applies to many types of errors, and there's more information about general debugging in the following article: Debugging why an image or video doesn't load in your application or site.

Errors specific to the remote image fetch URL feature

When fetching an image from a remote URL, the error may be with the URL that you've created, but it's also possible that the URL was valid and your account configuration disallowed the request, or that Cloudinary received an error from the remote server. 

Account configuration

It's possible to 'restrict' the ability to fetch images and videos into your account using unsigned URLs, and this can cause unexpected errors when using the remote image fetch URL feature. Please see the following screenshot from the Settings > Security tab:

If you try to fetch a new image using an unsigned URL while the feature is restricted, you may see a specific error:

X-Cld-Error: Images of type fetch are restricted in this account

Or a generic error: 

X-Cld-Error: Resource not found

In each case, you can resolve the issue by:

1) signing the URL,
2) removing the restriction in your security settings, or
3) by using the authenticated "explicit" API method to trigger fetching of the new image.

Parameter escaping

Sometimes the URL may be incorrect. For example, when trying to access the following link:

http://res.cloudinary.com/demo/image/fetch/https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcTm_o8s5J9-z2SAZ5yGfsD-fbZox4wGv1Fzlt0DIf4qrLbfgMZS5w

you'll see the following HTTP response header:

X-Cld-Error: Resource not found - https://encrypted-tbn1.gstatic.com/images

This error is returned because the URL that was requested includes query string parameters (after the "?") which are not part of our API, and are usually ignored by Cloudinary.

When we make a request to the remote server, those are not included and we'll receive an HTTP 404 error from the remote server. If query string parameters should be included in the request to the remote URL, those must be escaped in the request that you make to Cloudinary, and will become part of the asset's public_id in your Cloudinary account.

For this example, the solution is to either escape the '?' special character (by replacing it with '%3F'):

http://res.cloudinary.com/demo/image/fetch/https://encrypted-tbn1.gstatic.com/images%3Fq=tbn:ANd9GcTm_o8s5J9-z2SAZ5yGfsD-fbZox4wGv1Fzlt0DIf4qrLbfgMZS5w

Or to fully escape all special characters in the URL:

http://res.cloudinary.com/demo/image/fetch/https%3A%2F%2Fencrypted-tbn1.gstatic.com%2Fimages%3Fq%3Dtbn%3AANd9GcTm_o8s5J9-z2SAZ5yGfsD-fbZox4wGv1Fzlt0DIf4qrLbfgMZS5w

Similarly, if the remote server returns an image in all cases, but URL parameter values can change or modify the image that is returned, you may see that you don't get the expected image in the response. Escaping special characters in the URL so that they're sent to the remote server can also resolve such issues.

Other remote errors

Other URLs that appear OK may result in an error from the remote server. Where possible, Cloudinary will return the details of the error in the response.

For example, if you request a URL that does not return an image to Cloudinary, we'll mention that in the response, such as this example where the URL returned a HTML webpage instead of an image: