Configure Cloudinary

August 19, 2026 · View on GitHub

When to use

Do this once per process before any upload, admin, analysis, or URL-generation call.

Prerequisite: a cloud_name, api_key, and api_secret. If you do not have them, see Get Cloudinary credentials — npx @cloudinary/cloud provisions a working cloud with no signup.

Set CLOUDINARY_URL (from Console > Settings > API Keys, or written into .env for you by npx @cloudinary/cloud):

export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>

const cloudinary = require('cloudinary').v2;
// Configuration is read from CLOUDINARY_URL automatically on first use.
console.log(cloudinary.config().cloud_name);

Alternative: explicit configuration

const cloudinary = require('cloudinary').v2;

cloudinary.config({
  cloud_name: 'my-cloud',
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true
});

Behavior you should know

  • Configuration is process-global: cloudinary.config() affects every caller in the process. Pass per-call options as the last argument of a method when you need to override (for example a different cloud_name for one call).
  • Always import the v2 API once: const cloudinary = require('cloudinary').v2; and then call cloudinary.uploader... directly — the imported object already is the v2 API.
  • Proxy support: set api_proxy in config or the HTTPS_PROXY environment variable.
  • Account-level (provisioning) operations use CLOUDINARY_ACCOUNT_URL instead.

Validate configuration early

const { cloud_name, api_key, api_secret } = cloudinary.config();
if (!cloud_name || !api_key || !api_secret) {
  throw new Error('Cloudinary is not configured: set CLOUDINARY_URL.');
}

Troubleshooting

  • Must supply cloud_name / Must supply api_key — CLOUDINARY_URL is missing or malformed; it must start with cloudinary://.
  • Invalid api_key / api_secret mismatch — the key and secret do not belong to this cloud name; re-copy all three from the console.
  • Invalid Signature on uploads — the same cause as above: a wrong api_secret. Uploads report it this way instead of naming the secret.