Skip to content

troubleshoot-errors.md

Latest commit

 

History

History
83 lines (64 loc) · 3.57 KB

troubleshoot-errors.md

File metadata and controls

83 lines (64 loc) · 3.57 KB
Raw

Troubleshoot errors

How this SDK reports errors

Promise rejections and callback errors carry message and http_code. In debug mode, errors from API calls also include the Cloudinary request ID — include it in support tickets:

const cloudinary = require('cloudinary').v2;
cloudinary.config({ debug: true }); // adds request IDs to errors and logs

Errors by symptom

Must supply cloud_name / Must supply api_key

Configuration never loaded. Set CLOUDINARY_URL before the first call, or call cloudinary.config({...}) explicitly. See Configure Cloudinary.

Invalid api_key / api_secret mismatch

Key and secret do not match the cloud name. Re-copy all three from Console > Settings > API Keys. If you use multiple environments, check which one your process actually loaded.

Invalid Signature

A signed request included parameters that were not part of the signature, or values changed after signing. Sign every parameter the client sends. See Sign a browser upload.

Rate limit exceeded (Admin/Search API)

You are calling management APIs in a request path. Batch the work and cache results. Successful Admin responses carry rate_limit_remaining, so you can slow down before you are cut off. Delivery URLs are never rate-limited this way.

File size too large

Switch to chunked upload (upload_large).

423 Processing

The asset is still being processed and is not yet available for the operation you requested — common right after uploading a large video, or while an eager or add-on-driven transformation is still running. This is transient: retry with backoff rather than treating it as a failure. For long jobs, prefer eager_async with a notification_url over polling.

Delivery URL returns 400 or 404

The reason is in the X-Cld-Error response header of the failing URL (lowercase x-cld-error over HTTP/2):

curl -sI "https://res.cloudinary.com/<cloud_name>/image/upload/w_abc/sample.jpg" | grep -i '^x-cld-error'
# x-cld-error: Invalid width in transformation: abc

Typical values: Resource not found - <public_id> (wrong public ID, folder, or resource type in the URL path), Invalid <param> in transformation: <value>, and Unknown transformation <name> (the named transformation is missing on this environment). The header is CORS-exposed, so browser code can read it from a failed image fetch as well.

Upload succeeded but video will not transform or stream

The asset was uploaded as raw — upload_large defaults to resource_type: 'raw'. Re-upload with resource_type: 'video'.

403 / entitlement errors

The feature or add-on (for example the Analyze API or Visual Search) requires a subscription or account enablement. Check the add-ons page in the console; these are account capabilities, not SDK flags.

Timeouts

Pass timeout (milliseconds) in the call options. For uploads on unstable links, use chunked upload; chunks retry independently.

Stale delivery after re-upload

CDN-cached URLs do not update instantly. Deliver with the new version from the upload response, which changes the URL immediately. See Transform and deliver an image or a video.

Still stuck