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

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 synchronous transformations, whether on the fly or eager without eager_async=true. The limit depends on your plan, and it applies to transformation processing, not to the upload size.
• Solution: Use eager transformations with eager_async=true, set in an upload call, an upload preset, or the explicit method for videos you've already uploaded. Use eager_notification_url if you need a callback when processing finishes.

Derived video still processing (423)

Error example: Video tracking-crop is pending

• Cause: The response has a 423 status because the requested derived video is still being generated. This isn't a failure. Cloudinary processes some video transformations asynchronously, such as automatic content-aware cropping (g_auto), adaptive bitrate streaming, video previews, and transformations on long videos. The first request triggers the processing, so it's the first request that gets the 423.
• Solution: Retry the same URL once processing finishes. To avoid the wait, generate the derived video ahead of time with an eager transformation and eager_async=true, and use notifications to find out when it's ready. For more details, see 423 Locked.

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

g_auto must be in its own component

Error example: g_auto must be in a transformation component by itself

• Cause: For videos, automatic gravity must be in a transformation component that contains only the crop: the crop mode, g_auto, and the dimensions. Adding any other parameter to that component, such as an effect, quality, or trimming parameter, triggers this error. For example, c_fill,g_auto,h_300,w_300,e_blur:200 fails on a video, though the same component works on an image.
• Solution: Move the other parameters into separate chained components, for example c_fill,g_auto,h_300,w_300/e_blur:200

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

Signed URL stops working after a change

Error example: Unauthenticated access

• Cause: The URL has a signature or token, but it doesn't match the URL. This often happens when a signed URL is edited after signing. For authenticated videos, the signature covers the transformations as well as the public ID, so adding a parameter such as fl_no_stream to a working URL invalidates it.
• Solution: Generate the signature or token from the final delivery URL, including all its transformation parameters. See Unauthenticated access for more details.

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