vercel/ai · error · Error

Gemini image models do not support mask-based image editing.

Error message

Gemini image models do not support mask-based image editing.

What it means

The Google Vertex image model wrapper for Gemini image models (e.g. gemini-2.0-flash-exp image generation / Imagen-style Gemini endpoints) throws this plain Error from doGenerate when a `mask` option is supplied. Gemini image models do not expose a mask-based inpainting API, so the provider rejects the request up front instead of sending an unsupported parameter to the API.

Source

Thrown at packages/google-vertex/src/google-vertex-image-model.ts:81

      );
    }

    const {
      prompt,
      n,
      size,
      aspectRatio,
      seed,
      providerOptions,
      headers,
      abortSignal,
      files,
      mask,
    } = options;
    const warnings: Array<SharedV4Warning> = [];

    if (mask != null) {
      throw new Error(
        'Gemini image models do not support mask-based image editing.',
      );
    }

    if (n != null && n > 1) {
      throw new Error(
        'Gemini image models do not support generating a set number of images per call. Use n=1 or omit the n parameter.',
      );
    }

    if (size != null) {
      warnings.push({
        type: 'unsupported',
        feature: 'size',
        details:
          'This model does not support the `size` option. Use `aspectRatio` instead.',
      });
    }

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Remove the `mask` argument from the generateImage call when using a Gemini image model.
2. Switch to an Imagen model on Vertex (e.g. imagen-3.0-capability-001) if mask-based inpainting is required.
3. Express the edit purely through the prompt text for Gemini models (no mask region constraint).

Example fix

// before
await generateImage({ model: vertex.image('gemini-2.0-flash-exp-image'), prompt, mask });
// after
await generateImage({ model: vertex.image('imagen-3.0-capability-001'), prompt, mask }); // or omit mask for Gemini

if (mask) throw new Error('Gemini image models on Vertex do not support masks; use an Imagen model or omit the mask.');
await generateImage({ model: vertex.image(modelId), prompt, ...(mask ? {} : {}) });

try {
  await generateImage({ model, prompt, mask });
} catch (e) {
  if (e instanceof Error && e.message.includes('mask-based image editing')) {
    // fall back to Imagen or drop the mask
  } else throw e;
}

When it happens

Trigger: Calling generateImage (or the model's doGenerate) with a Gemini image model on @ai-sdk/google-vertex and passing `mask` (e.g. via generateImage's mask/abort options or provider options that map to mask) — the check `if (mask != null)` fires before any network call.

Common situations: Porting code that previously used Imagen 2 inpainting (which supports masks) to a Gemini image model; copying an OpenAI images/edits (dall-e mask) example onto the Vertex Gemini provider; passing a leftover mask variable that is null for one provider but set for another.

Related errors

• Gemini image models do not support generating a set number o
• AI_NoSuchModelError
• Unsupported task type: ${taskType}
• Amazon Bedrock request was moderated: ${reasons.join(', ')}
• Amazon Bedrock returned no images. Status: ${response.status

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/d7ce4108612f3039. Report an issue: GitHub.