How to diagnose 40x and X-Cld-Error messages when delivering assets

When a delivery URL fails, Cloudinary returns an HTTP 40X status and often adds detail in the X-Cld-Error response header. This article explains how to read those signals, why some errors keep appearing after you fix the underlying issue (CDN caching), and what each common X-Cld-Error message means—with fixes—for 400, 401, and 404 responses.

For a walkthrough, see the Diagnosing error codes video tutorial. For complex cases, contact Cloudinary support.

How to diagnose delivery errors

X-Cld-Error header

When Cloudinary can't deliver an asset as requested (or returns a substitute such as the default image placeholder), the response may include an X-Cld-Error HTTP header with a more specific reason.

You can inspect X-Cld-Error headers with your browser's developer tools. For step-by-step instructions on how to do this in different browsers, see the How to inspect errors manually.

See also: 'Introducing the X-Cld-Error header' video tutorial.

X-Cld-Error inspector tool

Use the tool below to inspect the X-Cld-Error header for a Cloudinary image URL. Paste the transformation URL and choose Inspect Headers.

HTTP status codes

The HTTP status (400, 401, 404, etc.) summarizes the outcome; X-Cld-Error (when present) narrows down the cause. The sections below are grouped by status code, with subsections for typical situations and for specific X-Cld-Error strings.

Cached 40X responses at the CDN

Cloudinary caches 40X error responses at the CDN per exact URL, using exponential backoff:

• The first cached 40X for a given URL lasts 1 minute.
• After that entry expires, if the same URL is requested and still fails, the next cached 40X lasts twice as long as the previous period (2 minutes, 4 minutes, 8 minutes, and so on), up to a maximum of 24 hours per cache segment.
• After that maximum, repeated failures can keep the error cached in 24-hour increments.

You see this most often as 404 on a transformation URL when the original asset wasn't in your cloud when you first tried to deliver the URL, or when the public_id specified in the URL doesn't match what you later uploaded.

Upload and delivery often run in different places—for example, one service uploads while another app or job only builds or loads transformation URLs. Those paths don't always finish in the same order, so a transformation URL can be requested before the asset exists.

In this case, the CDN may respond with a 40X (often 404) and cache that error response. Due to this caching, the URL can continue failing for a while even after the upload completes.

If you get a 40X (such as 404) and you've validated that the asset is in your cloud, a cached error for that exact URL is a likely explanation, especially if other transformation URLs for the same asset work.

Reduce or recover from cached errors

Prevent the issue: Upload the original (or apply the final public_id) before any code requests transformed URLs for that asset, so the first CDN hit isn't an error.

Work around an error that's already cached:

• Add the asset's version to the URL after upload so the URL string changes and isn't the cached failure.
• Use different transformation parameters or change the order of transformations so the URL isn't identical to the cached one.
• Use a default image placeholder (default_image / d in URLs) so delivery doesn't return a bare 404 while the asset is missing or while a cached error is still in effect.
• Invalidate the broken cached version so the new version can be immediately delivered instead
  • When renaming a public ID programmatically to one that is currently returning a cached 404, include the invalidate parameter in the rename request
  • If the asset you want to deliver already exists with the same public ID as one currently returning a cached 404 (for example, if you uploaded a new version of the asset without applying invalidate during the upload), use Explicit with the invalidate parameter set to true.

In general, when replacing an image with the same public_id: Upload with overwrite: true and invalidate: true so CDN copies of the old file and its derivatives are cleared. For example:

400 Bad Request

400 usually means the URL or transformation is invalid, malformed, or not allowed in the way it was requested—for example unknown transformation parameters or values (such as invalid tokens or w_0), or syntactically valid options that conflict (such as g_auto with a crop mode that doesn't support it).

Wrong URL structure also yields 400—for example if cloud_name appears after resource_type / type in the wrong place, or if transformation segments are embedded inside the public_id. See Transformation URL structure.

The subsections below describe frequent X-Cld-Error patterns for 400 and how to fix them.

Unknown or invalid referenced image <public_id> of type upload

• Cause: Cloudinary can't find the referenced image (e.g. in overlays or other references).
• What to do:
  • Confirm the public_id and that the resource still exists; fix any broken references in the request.
  • If the public_id contains slashes (e.g. animals/dog), use colons in overlay references (e.g. animals:dog).

Error in loading - <remote source URL>

• Cause: With fetch delivery, Cloudinary couldn't retrieve the remote file. X-Cld-Error is often Error in loading <URL> - <HTTP status from the remote>; Cloudinary returns 400 for that case. If the remote returns 404, Cloudinary more often returns 404 with Resource not found - <URL> instead. Causes include network issues, blocking, or the origin being down.
• What to do: Verify the URL; confirm the origin is up and reachable from the public internet; rule out access or rate limits on the remote.

Invalid transformation

• Cause: The transformation parameter or value is invalid, or the URL is malformed relative to supported syntax.
• What to do: Align parameters and values with the transformation reference and fix URL structure.

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

• Cause: g_auto is used with a resize mode that isn't a supported cropping mode (e.g. scale or fit).
• What to do: Use g_auto only with compatible modes (crop, fill, lfill, fill_pad, thumb, etc.), or remove g_auto if you need an incompatible mode.

public_id is too long

• Cause: For fetch delivery, the remote URL becomes the public_id. public_id length is limited (commonly 255 characters unless Cloudinary extends it for your account). Invalid transformation segments can be parsed as part of the public_id and trigger the same message.
• What to do: Upload from the remote URL via the API, use upload mapping, or ask support about a higher limit.

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

• Cause: On-the-fly (or non-async eager) video transforms exceed size limits (40MB on Free, 300MB on paid plans)—limits apply to transformation processing, not raw upload size.
• What to do: Run transforms eagerly and set eager_async=true (upload, upload presets, Explicit, or fetch). Use eager_notification_url if you need a callback when processing finishes.

401 Unauthorized

401 means delivery was blocked by an access rule: Strict transformations without an allowed/signed derived, restricted features in the product environment (Security), private or authenticated assets without a valid signed URL or token, or similar controls.

ACL deny

• Cause: Cloudinary returns 401 with ACL deny in X-Cld-Error when ACL rules, fetch allowlists, or related policies block the request. Other denials (e.g. token-based access or PDF / archive restrictions on free plans) can produce similar 401 responses; the exact X-Cld-Error text may differ.
• What to do:
  • Review ACL dimensions you configured (country, IP, path, content-type, referrer, user-agent)
  • For tokens: Make sure they are valid, correctly formatted, unexpired, and properly signed
  • For free-plan PDF/archives, see the Media delivery guide; contact support if needed

404 Not Found

404 means the requested resource wasn't found, unless you use a default / placeholder image transformation—in which case the response may still succeed with a substitute while X-Cld-Error can describe the underlying miss.

If 404 persists for a URL that should work after a recent upload or rename, see Cached 40X responses at the CDN above.

Resource not found - <public_id>

• Cause: No resource matches the public_id (typo, deletion, or wrong path).
• What to do:
  • Verify public_id and that the file still exists.
  • Confirm resource_type and delivery_type in the URL (image/upload, image/private, video/upload, etc.).
  • Look through your transformation parameters. If there's one that's missing an underscore, Cloudinary might try to resolve it as part of the public ID path. For example, cartoonify/my_image, when you intended e_cartoonify/my_image.

Resource not found (public ID isn't specified in the error message)

• Cause: The real reason is hidden for security—for example the URL may need a signature (private/authenticated assets, or add-ons that require signed URLs).
• What to do: Check whether the asset or flow requires signed URLs. On paid plans, the Error report may show the underlying message; otherwise support can confirm or help adjust settings.

Resource not found - <URL> (fetch)

When fetch is used and the remote returns 404, X-Cld-Error often includes Resource not found - <URL> with HTTP 404 (contrast with 400 “Error in loading” for other remote HTTP failures, described under 400 above).