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 doesn't work due to CORS restrictions, 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 - 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: Use auto gravity only with crop, fill, lfill, fill_pad or thumb

• 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, or thumb

Overlay image not found

Error example: Unknown or invalid referenced image <public_id> of type upload

• 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)

Add-on requires signed URL

Error example: Can't generate images using add-ons if URL isn't signed

• Cause: Using an add-on feature that requires URL signing
• Solution: Generate a signed URL or enable the add-on in "Allow unsigned add-on transformations" in your Console Security settings

Additional troubleshooting resources