Troubleshooting image transformation errors

When working with Cloudinary image transformation URLs, you may encounter errors due to invalid syntax, unsupported parameter values, or conflicting transformation options. This page helps you diagnose and resolve common transformation errors using the X-Cld-Error response header.

Understanding transformation errors

If you encounter a problem when accessing a Cloudinary transformation URL (such as a blank result, a 400 error, or unexpected output), Cloudinary reports the error details in the X-Cld-Error HTTP response header.

Common transformation error scenarios include:

• Invalid syntax: Using incorrect parameter names or values (e.g., w_abc instead of w_300)
• Conflicting parameters: Combining transformation options that don't work together (e.g., using g_auto with incompatible crop modes)
• Unsupported features: Attempting to use features not available on your plan or not enabled for your account
• Missing resources: Referencing overlay images or fonts that don't exist

X-Cld-Error inspector tool

Use the interactive tool below to quickly inspect the X-Cld-Error header for any Cloudinary image URL. Simply paste your transformation URL and click "Inspect Headers" to see if there are any errors reported.

How to inspect errors manually

If the tool above fails to retrieve headers, you can inspect the X-Cld-Error header manually using your browser's Developer Tools:

Chrome / Edge

1. Open Developer Tools (View > Developer > Developer Tools, or press F12)
2. Click the Network tab
3. Reload the page or navigate to the Cloudinary URL
4. Find the request in the network list
5. Click on it to view details
6. Look for X-Cld-Error under the Response Headers section

Firefox

1. Open Developer Tools (Tools > Browser Tools > Web Developer Tools, or press F12)
2. Click the Network tab
3. Reload the page or navigate to the Cloudinary URL
4. Find the request and click on it
5. Click the Headers tab
6. Look for X-Cld-Error under Response Headers

Safari

1. Enable Developer menu (Preferences > Advanced > Show Develop menu)
2. Open Web Inspector (Develop > Show Web Inspector, or press Cmd+Option+I)
3. Click the Network tab
4. Reload the page or navigate to the Cloudinary URL
5. Select the request
6. Look for X-Cld-Error in the response headers

Common image transformation errors

Invalid parameter values

Error example: Invalid width in transformation: abc

• Cause: Using a non-numeric value for a parameter that expects numbers
• Solution: Ensure numeric parameters like w (width), h (height), q (quality) use valid integer or decimal values

Gravity parameter conflicts

Error example: Auto gravity can only be used with crop, fill, thumb, lfill

• Cause: Attempting to use g_auto with incompatible crop modes like scale or fit
• Solution: Use g_auto only with supported crop modes: crop, fill, lfill, fill_pad, auto, auto_pad, or thumb

Overlay image not found

Error example: Unknown or invalid referenced image <public_id> of type upload: Resource not found - <public_id>

• Cause: The overlay image specified with l_<public_id> doesn't exist
• Solution: Verify the public ID is correct, and replace slashes with colons in folder paths (e.g., l_folder:image instead of l_folder/image)

URL requires a signature

Error example: Resource not found

• Cause: Possibly using an add-on feature that requires URL signing, or the image is private or authenticated
• Solution: Generate a signed URL or enable the add-on in "Unsigned add-on transformations allowed" in your Console Security settings

Base image not found

Error example: Resource not found - <public_id>

• Cause: The base image, <public_id>, doesn't exist
• Solution: Double-check that the public ID is correct, the asset exists in your Cloudinary account, and you are referencing the right resource type (e.g., image, video). If your asset is in a folder and your account uses fixed folders, ensure you're including the folder path in the public ID, using forward slashes, not colons.

Additional troubleshooting resources