{"record":{"id":"d7ce4108612f3039","repo":"vercel/ai","slug":"gemini-image-models-do-not-support-mask-based-imag","errorCode":null,"errorMessage":"Gemini image models do not support mask-based image editing.","messagePattern":"Gemini image models do not support mask-based image editing\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/google-vertex/src/google-vertex-image-model.ts","lineNumber":81,"sourceCode":"      );\n    }\n\n    const {\n      prompt,\n      n,\n      size,\n      aspectRatio,\n      seed,\n      providerOptions,\n      headers,\n      abortSignal,\n      files,\n      mask,\n    } = options;\n    const warnings: Array<SharedV4Warning> = [];\n\n    if (mask != null) {\n      throw new Error(\n        'Gemini image models do not support mask-based image editing.',\n      );\n    }\n\n    if (n != null && n > 1) {\n      throw new Error(\n        'Gemini image models do not support generating a set number of images per call. Use n=1 or omit the n parameter.',\n      );\n    }\n\n    if (size != null) {\n      warnings.push({\n        type: 'unsupported',\n        feature: 'size',\n        details:\n          'This model does not support the `size` option. Use `aspectRatio` instead.',\n      });\n    }","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/google-vertex/src/google-vertex-image-model.ts#L63-L99","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the `mask` argument from the generateImage call when using a Gemini image model.","Switch to an Imagen model on Vertex (e.g. imagen-3.0-capability-001) if mask-based inpainting is required.","Express the edit purely through the prompt text for Gemini models (no mask region constraint)."],"exampleFix":"// before\nawait generateImage({ model: vertex.image('gemini-2.0-flash-exp-image'), prompt, mask });\n// after\nawait generateImage({ model: vertex.image('imagen-3.0-capability-001'), prompt, mask }); // or omit mask for Gemini","handlingStrategy":"validation","validationCode":"if (mask) throw new Error('Gemini image models on Vertex do not support masks; use an Imagen model or omit the mask.');\nawait generateImage({ model: vertex.image(modelId), prompt, ...(mask ? {} : {}) });","typeGuard":null,"tryCatchPattern":"try {\n  await generateImage({ model, prompt, mask });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('mask-based image editing')) {\n    // fall back to Imagen or drop the mask\n  } else throw e;\n}","preventionTips":["Keep a per-model capability map (supportsMask, maxImages) in your app and validate options before calling generateImage.","Never share one options object containing mask/n across Imagen, Gemini, and OpenAI image calls."],"tags":["unsupported-parameter","image-generation","google-vertex","gemini"],"backgroundTag":"unsupported-model-capability","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}