Why do I get a 'XXX parameter is not allowed' error on unsigned uploads?

When performing unsigned uploads, Cloudinary only allows a limited set of parameters to be passed directly in the upload call. Attempting to use unsupported parameters, results in an error.

The error

When you try to pass an unsupported parameter, such as transformation, directly in an unsigned upload call, you receive an error response similar to:

Or in the X-Cld-Error response header:

Why this happens

For security reasons, unsigned uploads have protective limitations. Since unsigned uploads don't require authentication, Cloudinary restricts which parameters you can pass directly to prevent potential misuse. Specifically, you can pass only parameters from this allowed list directly in an unsigned upload call.

The solution

Move restricted parameters into your upload preset configuration instead of passing them directly in the upload call.

Step 1: Create or update your upload preset

Create an upload preset or update the existing one to include the restricted parameters you need.

Step 2: Remove restricted parameters from your upload call

Remove any restricted parameters from your upload call. The parameters you defined in the preset are applied automatically:

Example: Creating a preset with transformations

The following example creates an unsigned upload preset that applies an incoming transformation to resize and crop images:

Now you can use this preset for unsigned uploads, and the transformation is applied automatically: