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

Gemini image models do not support mask-based inpainting/image editing, so the provider throws immediately when a `mask` is supplied in doGenerate options. This is an explicit capability guard rather than a propagated API error.

Source

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

    }

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

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

    // Gemini does not support generating multiple images per call via n parameter
    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

Remove the `mask` option when using Gemini image models
Perform mask-based editing with a provider that supports it (e.g. OpenAI image editing)
Send the masked/composited image as part of the prompt input image instead of using a mask parameter

Example fix

// before
await generateImage({ model: google.imageModel('gemini-2.5-flash-image'), prompt, mask });
// after
await generateImage({ model: google.imageModel('gemini-2.5-flash-image'), prompt });

Defensive patterns

Strategy: validation

Validate before calling

if (options.mask != null) {
  throw new Error('Gemini image models do not support masks; remove the mask option.');
}

Type guard

function supportsMaskEditing(modelId: string): boolean {
  return !modelId.startsWith('gemini-');
}

Try / catch

try {
  await generateImage({ model, prompt, ...(mask ? { mask } : {}) });
} catch (error) {
  if (error instanceof Error && error.message.includes('mask-based image editing')) {
    // retry without mask or route to a mask-capable provider
  }
  throw error;
}

Prevention

Only pass `mask` for providers known to support inpainting
Keep provider-specific options behind a capability flag in multi-provider code
Check the model capability docs before adding mask editing

When it happens

Trigger: Calling generateImage (or doGenerate) against a Google Gemini image model with a `mask` property set in provider options or image editing options.

Common situations: Porting image-editing code from providers that support inpainting masks (e.g. OpenAI DALL·E editing) to Google Gemini; generic multi-provider image editing code that always passes a mask.

Related errors

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