# Cloudinary - Troubleshooting

Use when diagnosing errors or unexpected behavior across any Cloudinary product: transformation errors, delivery failures, upload issues, Media Library errors, account and billing questions, or integration-specific problems.

> Fragment of the documentation discovery map. Full index: https://cloudinary.com/documentation/llms.txt

## Image and Video APIs

### Cloudinary Image

- [Troubleshooting and tips](https://cloudinary.com/documentation/cloudinary_image_troubleshooting_tips.md): This section provides troubleshooting guidance and useful tips related to Cloudinary Image.
  - [Troubleshooting image transformation errors](https://cloudinary.com/documentation/ts_troubleshooting_image_transformation_errors.md): Use the interactive X-Cld-Error inspector tool to diagnose and resolve common image transformation errors. Learn how to inspect error headers and fix invalid syntax, parameter conflicts, and other transformation issues.
  - [40x errors and X-Cld-Error messages](https://cloudinary.com/documentation/ts_what_are_the_common_error_codes_returned_in_the_x_cld_error_header_when_delivering_assets.md): A reference guide to troubleshoot and resolve common X-Cld-Error messages returned by Cloudinary when delivering assets, with causes and solutions for each error.
  - [Add a solid color overlay](https://cloudinary.com/documentation/ts_how_to_add_a_solid_color_overlay.md): Learn how to apply solid color overlays to images using a 1x1 pixel image, with options to resize, recolor, position automatically, and adjust opacity.
  - [Images delivered without gzip compression](https://cloudinary.com/documentation/ts_why_are_my_cloudinary_images_delivered_without_gzip_compression_content_encoding.md): Cloudinary gzips only compressible formats. For certain formats like JPG and PNG, applying gzip compression is redundant and may not yield any gain. Furthermore, sometimes it may even result in larger files.
  - [Long time to first byte (TTFB) on WebPageTest.org](https://cloudinary.com/documentation/ts_why_am_i_seeing_a_long_time_to_first_byte_ttfb_on_webpagetest_org.md): WebPageTest is a common tool that is used to examine site performance. It can generate a beautifully detailed waterfall with information on each request.
  - [Update a named transformation](https://cloudinary.com/documentation/ts_how_can_i_update_a_named_transformation.md): Learn different methods to update a named transformation in Cloudinary, including using the management console, Admin API, and CLI SDK to regenerate derived assets.
  - [Cloudinary vs Imagga cropping](https://cloudinary.com/documentation/ts_what_is_the_difference_between_cloudinary_automated_cropping_and_imagga_smart_cropping.md): Understand the differences between Cloudinary's built-in content-aware cropping and the Imagga smart cropping add-on, including algorithm differences, configuration options, and quota considerations.
  - [Placeholder images (LQIP)](https://cloudinary.com/documentation/ts_suggested_transformation_options_for_placeholder_images_lqip.md): Suggested transformation options for placeholder images/ LQIP – Cloudinary Support
  - [How to detect corrupted images](https://cloudinary.com/documentation/ts_how_to_detect_corrupted_images.md): Learn how to identify and handle corrupted JPEG images during upload by using the IsCorrupt parameter.
  - [Force specific image when sharing links on Facebook](https://cloudinary.com/documentation/ts_how_can_i_force_a_specific_image_to_feature_when_sharing_my_links_on_facebook.md): Facebook provides a dedicated API to personalize the preview of shared links. Specifically, the og:image property allows you to specify the image that's displayed as a thumbnail.
  - [Blurry images](https://cloudinary.com/documentation/ts_why_is_my_image_blurry.md): Image blurriness can occur for several reasons. Two of the most common reasons and potential solutions are listed below.
  - [Offset face-detection gravity](https://cloudinary.com/documentation/ts_how_to_offset_face_detection_gravity_when_cropping.md): Learn how to nudge or offset the crop position relative to a detected face using the zoom parameter and a two-step crop workaround.
### Cloudinary Video

- [Troubleshooting and tips](https://cloudinary.com/documentation/cloudinary_video_troubleshooting_tips.md): This section provides troubleshooting guidance and useful tips related to Cloudinary Video.
  - [Troubleshooting video transformation errors](https://cloudinary.com/documentation/ts_troubleshooting_video_transformation_errors.md): Use the interactive X-Cld-Error inspector tool to diagnose and resolve common video transformation errors. Learn how to inspect error headers and fix invalid syntax, parameter conflicts, and other transformation issues.
  - [Video duration missing on first play](https://cloudinary.com/documentation/ts_video_duration_not_shown_during_first_playback.md): Explains why on-the-fly transformed videos don't show total duration initially and how to resolve it using eager transformations.
  - [Remove codec from Content-Type](https://cloudinary.com/documentation/ts_video_content_type_includes_codec.md): Fix the Content-Type video/mp4;codecs=avc1 header that some services reject by applying a video codec transformation.
### Upload

- [Troubleshooting and tips](https://cloudinary.com/documentation/upload_images_troubleshooting_tips.md): This section provides troubleshooting guidance and useful tips related to uploading assets.
  - [Unsigned upload from Google Apps Script](https://cloudinary.com/documentation/ts_how_to_perform_an_unsigned_image_upload_from_google_apps_script_to_cloudinary.md): Google Apps Script does not have native support for the FormData object used in JavaScript for handling file uploads. However, you can still upload images to Cloudinary by using a simple JSON object instead.
  - [Rejected file formats](https://cloudinary.com/documentation/ts_why_does_cloudinary_reject_the_file_format_of_some_files_im_uploading.md): Learn which file extensions are blocked by Cloudinary for security reasons and how to request exceptions for paid accounts.
  - [Troubleshooting failed upload requests](https://cloudinary.com/documentation/ts_troubleshooting_failed_upload_requests.md): Learn how to troubleshoot failed upload requests by checking X-Cld-Error messages from API uploads and error messages from the Upload Widget, and understand common error reasons like configuration issues and account limits.
  - [Always upload a square image](https://cloudinary.com/documentation/ts_how_to_always_upload_a_square_image.md): When uploading images to Cloudinary you can specify the dimensions and crop to always upload a square image.
  - [Unsupported parameters in unsigned uploads](https://cloudinary.com/documentation/ts_unsupported_parameters_in_unsigned_uploads.md): Learn why unsigned uploads restrict certain parameters and how to apply restricted parameters through upload presets.
  - [Uploaded image truncated](https://cloudinary.com/documentation/ts_why_was_my_uploaded_image_truncated.md): Learn how to detect and handle truncated images when uploading from remote servers, including using the IsCorrupt attribute for JPEG files.
  - [Upload failed - cloud_name is disabled error](https://cloudinary.com/documentation/ts_why_am_i_receiving_an_upload_failed_cloud_name_is_disabled_error_when_using_my_new_cloudinary_account.md): When you register for a Cloudinary account, a verification email is sent to complete the signup process. If email verification is not completed, your account cannot be used and API calls will return errors.
  - [Upload with FileMaker](https://cloudinary.com/documentation/ts_integrating_cloudinary_with_filemaker.md): Perform signed uploads from FileMaker using scripting features.
### Asset management

- [Troubleshooting and tips](https://cloudinary.com/documentation/asset_management_troubleshooting_tips.md): Troubleshooting guidance and useful tips related to asset management.
  - [Admin API authentication issues](https://cloudinary.com/documentation/ts_admin_api_authentication_issues.md): Learn how to troubleshoot Admin API authentication problems when receiving HTML responses instead of JSON data.
  - [Why has the public ID of my asset changed?](https://cloudinary.com/documentation/ts_why_has_the_public_id_of_my_asset_changed.md): Learn why an asset's public ID might change in Cloudinary and how to manage these changes effectively.
  - [Check resource type and delivery type](https://cloudinary.com/documentation/ts_how_to_view_resource_type_and_delivery_type.md): Learn how to verify the resource type and delivery type of uploaded assets by examining the delivery URL or checking the Console.
  - [Get image or video dimensions](https://cloudinary.com/documentation/ts_how_can_i_get_the_size_or_dimensions_of_an_image_by_its_public_id.md): Learn multiple methods to retrieve image and video dimensions, including via API responses, Admin API queries, and the Console UI.
  - [Download account assets](https://cloudinary.com/documentation/ts_how_can_i_download_my_accounts_assets.md): Cloudinary supports several ways to download many or all of your assets from your account. Depending on your requirements, the size of your account, and whether you are using Cloudinary's UI or API, you can choose from several options.
  - [Delete or modify original images](https://cloudinary.com/documentation/ts_dam_how_can_i_delete_or_modify_the_original_image_uploaded.md): Learn how to delete original assets and their derived versions, or modify original images using incoming transformations.
  - [Does Cloudinary store any cookies?](https://cloudinary.com/documentation/ts_does_cloudinary_store_any_cookies.md): Learn about Cloudinary's cookie usage policy, including how cookies are handled in asset delivery requests and when using widgets with third-party services.
  - [Underscores in public IDs or folder names](https://cloudinary.com/documentation/ts_why_shouldnt_i_use_underscore_within_folder_names.md): Using underscores in the first few letters of a public ID containing slashes or in a folder name (in fixed-folder mode) can create ambiguity and result in broken URLs. Learn best practices to prevent these errors.
  - [Update already fetched asset](https://cloudinary.com/documentation/ts_how_to_update_an_already_fetched_asset.md): Learn how to update an asset that was previously fetched and then updated via the original remote URL using the UI or API methods.
  - [Upload, manage, and deliver PDFs](https://cloudinary.com/documentation/ts_how_to_upload_manage_and_deliver_pdf_files.md): Learn how to upload, manage, transform, and deliver PDF files in Cloudinary, including conversions, text extraction, and security settings.
  - [Cloudinary "sample" images](https://cloudinary.com/documentation/ts_how_can_i_delete_the_sample_image.md): Learn why Cloudinary automatically recreates the sample images (cld-sample to cld-sample-5) and how to replace them with your own images.
  - [Avoiding duplicate uploads](https://cloudinary.com/documentation/ts_how_can_cloudinary_help_me_to_avoid_or_detect_duplicated_uploads_in_my_account.md): Learn how to use MD5 signatures, pHash similarity checks, ETag as public_id, and the Duplicate Image Detection add-on to avoid or detect duplicate uploads.
  - [Permitted naming conventions](https://cloudinary.com/documentation/ts_permitted_naming_conventions.md): Reference for the allowed length, characters, and other naming rules for Cloudinary cloud names and asset public IDs.
  - [Adult/NSFW content policy](https://cloudinary.com/documentation/ts_does_cloudinary_support_adult_nsfw_content.md): Learn about Cloudinary's policy on adult/NSFW content and how to handle user-uploaded content that may violate terms of service.
  - [High transformation rate](https://cloudinary.com/documentation/ts_why_does_my_accounts_usage_report_show_a_relatively_high_transformation_rate.md): Learn about common operations and features that can result in higher transformation counts than expected, including uploads, auto formatting, and responsive design.
### Account management

- [Troubleshooting and tips](https://cloudinary.com/documentation/account_management_troubleshooting_tips.md): Find troubleshooting tips and answers to commonly asked questions about Cloudinary account management.
  - [Cancel or delete Cloudinary account](https://cloudinary.com/documentation/ts_how_can_i_cancel_or_delete_my_cloudinary_account.md): Learn the difference between canceling and deleting your Cloudinary account, and how to request permanent account deletion.
  - [Sign up or add user with existing email](https://cloudinary.com/documentation/ts_how_to_create_a_new_account_using_an_email_address_with_pre_existing_account.md): Resolves the "Has already been taken" or "This email already exists" error when attempting to create a new account or add a user to an existing account with an email that's currently associated with another Cloudinary account.
  - [Credit card payments](https://cloudinary.com/documentation/ts_does_cloudinary_support_credit_card_payments.md): Learn about credit card payment options with Cloudinary, how to set up and update payment methods, and what to do if a payment fails.
  - [Recover disabled account](https://cloudinary.com/documentation/ts_why_is_my_account_disabled_and_how_can_i_recover_my_disabled_account.md): Learn why your Cloudinary account may be disabled due to exceeding your plan's quota or payment failure, and how to re-enable it.
  - [Can't downgrade my plan](https://cloudinary.com/documentation/ts_why_cant_i_downgrade_my_plan.md): Explains each reason Cloudinary may block a plan downgrade — including usage overages, unsupported features, active add-ons, and unpaid invoices — and how to resolve each one.
  - [Migrate Media Optimizer account](https://cloudinary.com/documentation/ts_how_can_i_migrate_existing_account_media_optimizer_programmable_media.md): Media Optimizer is no longer available. Learn your options for creating a new Programmable Media account using the same email address.
  - [Why did my usage spike?](https://cloudinary.com/documentation/ts_usage_spike.md): Diagnose a sudden increase in Cloudinary storage, transformation, or bandwidth usage and determine whether you need to upgrade your plan.
  - [Rotate API keys in the Console](https://cloudinary.com/documentation/ts_how_to_rotate_api_keys_in_the_console.md): Generate a new API key and secret, update your application configuration, then disable the old key to rotate credentials without downtime.
  - [Successfully go live with Cloudinary](https://cloudinary.com/documentation/ts_how_to_successfully_go_live_or_launch_a_new_activity_with_cloudinary.md): Best practices for launching Cloudinary implementations, covering planning stages, development review, deployment coordination with support teams, and post-deployment monitoring of reports and error consoles.
  - [Bot traffic and access control](https://cloudinary.com/documentation/ts_bot_traffic_usage_spikes_access_control_best_practices.md): Learn why Cloudinary is not your primary bot mitigation layer, and how to use upstream CDN/WAF controls alongside Cloudinary access controls.
## Cloudinary Assets

### Admin guides

- [Troubleshooting and tips](https://cloudinary.com/documentation/dam_media_library_administration_troubleshooting_tips.md): Troubleshooting guidance and useful tips related to Assets administration, answering questions commonly asked by Cloudinary customers.
  - [Common Media Library errors](https://cloudinary.com/documentation/ts_dam_what_are_the_common_errors_encountered_in_the_media_library.md): Learn about common errors you may come across when using the Media Library, the main way to navigate and manage folders and assets within your Cloudinary product environment.
  - [Setup 2FA without mobile camera](https://cloudinary.com/documentation/ts_dam_setup_2fa_using_the_front_camera_of_my_mobile_phone.md): Learn how to bypass the need to photograph a QR code if your mobile phone's primary camera isn't functional.
  - [Export asset details to CSV](https://cloudinary.com/documentation/ts_dam_how_to_export_asset_details_to_csv.md): Learn multiple methods to export asset details from your Cloudinary account to CSV format, including apps, CLI, and custom API solutions.
  - [Adult/NSFW content policy](https://cloudinary.com/documentation/ts_dam_does_cloudinary_support_adult_nsfw_content.md): Learn about Cloudinary's policy on adult/NSFW content and how to use moderation tools to detect and remove such content from your account.
  - [Pending user status](https://cloudinary.com/documentation/ts_dam_what_does_pending_mean_in_the_user_s_status_section.md): Learn what the "pending" user status means and how to resend a verification email when the invitation link expires.
## Integrations

### WordPress Plugin

- [Troubleshooting and tips](https://cloudinary.com/documentation/int_wordpress_troubleshooting_tips.md): Troubleshooting tips and guidance for common questions related to the Cloudinary WordPress plugin.
  - [Duplicated assets on resync](https://cloudinary.com/documentation/ts_int_wordpress_assets_duplicated_resync.md): Learn why the Cloudinary WordPress plugin duplicates assets during resync and how to identify actual duplicates using the guid contextual metadata.
### Page Designer Cartridge

- [Troubleshooting and tips](https://cloudinary.com/documentation/salesforce_page_designer_troubleshooting_tips.md): Troubleshooting guidance and useful tips related to the Salesforce Commerce Cloud Page Designer cartridge.
  - [Can't insert images in PageDesigner](https://cloudinary.com/documentation/ts_int_why_cant_i_insert_images_from_cloudinary_dam_in_sfcc_pagedesigner.md): Resolves certificate issues when using domain aliases in SFCC sandbox that prevent Cloudinary components from functioning in PageDesigner.
### Salesforce Marketing Cloud App

- [Troubleshooting and tips](https://cloudinary.com/documentation/int_salesforce_marketing_cloud_app_troubleshooting_tips.md): Find troubleshooting guidance and useful tips for working with the Cloudinary Salesforce Marketing Cloud App integration.
  - [Reset makes preview image larger](https://cloudinary.com/documentation/ts_int_clicking_reset_in_the_sfmc_advanced_tab_makes_the_preview_image_larger.md): Explains why clicking Reset in the SFMC advanced tab causes the preview image to become larger and provides workarounds for this known issue.