CherryHQ/cherry-studio · 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

Thrown by the gateway Gemini image adapter's `doGenerate` when `options.mask` is non-null. Gemini image models (e.g. `gemini-3-pro-image`) perform edits through full-image natural-language prompts, not mask-based inpainting; passing a mask would be silently ignored, so the adapter rejects it outright to match `@ai-sdk/google`'s behavior.

Source

Thrown at src/main/ai/provider/custom/gateway/gatewayImageModel.ts:53

/**
 * Wrap a gateway `LanguageModelV3` as an `ImageModelV3` that drives image
 * generation through the language API with `responseModalities: ['IMAGE']`.
 */
export function createGatewayGeminiImageModel(languageModel: LanguageModelV3, modelId: string): ImageModelV3 {
  return {
    specificationVersion: 'v3',
    provider: GATEWAY_GOOGLE_IMAGE_PROVIDER,
    modelId,
    // Gemini returns a single image per generateContent call.
    maxImagesPerCall: 1,
    async doGenerate(options: ImageModelV3CallOptions) {
      const { prompt, n, size, aspectRatio, seed, files, mask, providerOptions, headers, abortSignal } = options
      const warnings: Awaited<ReturnType<ImageModelV3['doGenerate']>>['warnings'] = []

      if (mask != null) {
        // Gemini edits via full-image prompts, not masks. Match @ai-sdk/google,
        // which rejects mask-based editing outright rather than ignoring it.
        throw new Error('Gemini image models do not support mask-based image editing.')
      }
      if (n != null && n > 1) {
        warnings.push({
          type: 'unsupported',
          feature: 'n',
          details: 'Gemini image models generate a single image per call. Extra images were not requested.'
        })
      }
      if (size != null) {
        warnings.push({
          type: 'unsupported',
          feature: 'size',
          details: 'This model does not support `size`. Use `aspectRatio` instead.'
        })
      }

      // Build the user turn: prompt text + any input images (editing support).
      const userContent: Array<

View on GitHub (pinned to 726446b54c)

Solutions

1. Do not send a mask for Gemini image models — express the edit as a text prompt over the full input image instead.
2. Route mask-based editing to a model that supports it (e.g. a DashScope wanx2.1-imageedit model).
3. In the UI, disable/hide the mask tool when a Gemini image model is selected.

Example fix

// before
gatewayImageModel.doGenerate({ prompt, files, mask, ... })
// after — Gemini edits by prompt over the whole image
gatewayImageModel.doGenerate({ prompt: 'remove the background', files, /* mask omitted */ })

if (isGatewayGeminiImageModel(modelId) && options.mask != null) {
  throw new Error('Gemini image models cannot use a mask — use prompt-based editing instead')
}

const supportsMask = (modelId: string): boolean =>
  !isGatewayGeminiImageModel(modelId)

try {
  await model.doGenerate(opts)
} catch (e) {
  if (e instanceof Error && /mask-based image editing/.test(e.message)) {
    // drop the mask and retry with prompt-only editing
  }
  throw e
}

When it happens

Trigger: Calling image generation on a Gemini image model via the gateway with a mask supplied — e.g. an inpainting/edit flow that passes `options.mask`.

Common situations: A generic image-edit UI that always sends a mask regardless of model; switching an edit workflow from a mask-capable model (e.g. wanx imageedit) to Gemini without dropping the mask; assuming all edit-capable models accept masks.

Related errors

• ${label} returned non-JSON (HTTP ${response.status})
• local-embedding provider only supports text embeddings, not

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/3b6d4cb056f3b037. Report an issue: GitHub.