Troubleshooting video transformation errors

When working with Cloudinary video 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 video 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)
• Video size limits: Attempting on-the-fly transformations on videos that exceed size thresholds
• Unsupported features: Attempting to use features not available on your plan or not enabled for your account
• Missing resources: Referencing overlay videos, images, or audio files 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 video 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 video 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

Video too large for on-the-fly processing

Error example: Video is too large to process synchronously, please use an eager transformation with eager_async=true to resolve

• Cause: Video exceeds the size limit for on-the-fly transformations (40MB for Free plans, 300MB for paid plans)
• Solution: Use eager transformations with eager_async=true, or use the explicit method to generate transformations asynchronously

Gravity parameter conflicts

Error example: g_auto only supports fill,fill_pad

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

Overlay resource not found

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

• Cause: The overlay video specified doesn't exist
• Solution: Verify the public ID is correct, and replace slashes with colons in folder paths (e.g., l_video:folder:clip instead of l_video/folder/clip)

URL requires a signature

Error example: Resource not found

• Cause: Possibly using an add-on feature that requires URL signing, or the video 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 video not found

Error example: Resource not found - <public_id>

• Cause: The base video, <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