vercel/ai · error · Error

Luma AI does not support mask-based image editing. Use the p

Error message

Luma AI does not support mask-based image editing. Use the prompt to describe the changes you want to make, along with `prompt.images` containing the source image URL.

What it means

Thrown by getEditingOptions when an image editing request includes a mask. Luma's image API does not support mask-based inpainting, so the SDK rejects masks up front instead of sending an unsupported parameter to the API. The guidance is to express edits via the prompt and supply the source image through prompt.images.

Source

Thrown at packages/luma/src/luma-image-model.ts:235

  private createLumaErrorHandler() {
    return createJsonErrorResponseHandler({
      errorSchema: lumaErrorSchema,
      errorToMessage: (error: LumaErrorData) =>
        error.detail[0].msg ?? 'Unknown error',
    });
  }

  private getEditingOptions(
    files: ImageModelV4File[] | undefined,
    mask: ImageModelV4File | undefined,
    referenceType: LumaReferenceType = 'image',
    imageConfigs: Array<{ weight?: number | null; id?: string | null }> = [],
  ): Record<string, unknown> {
    const options: Record<string, unknown> = {};

    // Luma does not support mask-based inpainting
    if (mask != null) {
      throw new Error(
        'Luma AI does not support mask-based image editing. ' +
          'Use the prompt to describe the changes you want to make, along with ' +
          '`prompt.images` containing the source image URL.',
      );
    }

    if (files == null || files.length === 0) {
      return options;
    }

    // Validate all files are URL-based
    for (const file of files) {
      if (file.type !== 'url') {
        throw new Error(
          'Luma AI only supports URL-based images. ' +
            'Please provide image URLs using `prompt.images` with publicly accessible URLs. ' +
            'Base64 and Uint8Array data are not supported.',
        );

View on GitHub (pinned to 69428b1f8b)

Solutions

Remove the mask from the request entirely.
Describe the desired edit in the prompt text (e.g. 'replace the sky with a sunset').
Pass the source image via prompt.images as a publicly accessible URL.
If mask-based inpainting is a hard requirement, use a provider that supports it (e.g. OpenAI) instead of Luma.

Example fix

// before
await generateImage({
  model: luma.image('photon-flash-1'),
  prompt: { text: 'remove the car', images: [{ type: 'url', url: src }], mask: maskUrl },
});
// after
await generateImage({
  model: luma.image('photon-flash-1'),
  prompt: { text: 'remove the car', images: [{ type: 'url', url: src }] },
});

Defensive patterns

Strategy: validation

Validate before calling

function assertNoMask(images) {
  if (images && images.some(i => 'mask' in i && i.mask != null)) {
    throw new Error('Luma does not support masks; describe edits in the prompt instead');
  }
}

Type guard

function hasMask(p: { images?: Array<{ mask?: unknown }> }): boolean {
  return p.images?.some(i => i.mask != null) ?? false;
}

Try / catch

try {
  await generateImage({ model: lumaImage, prompt });
} catch (e) {
  if (e instanceof Error && e.message.includes('mask-based image editing')) {
    // fall back: strip mask and rely on prompt-only editing
    const { mask, ...rest } = prompt;
    return generateImage({ model: lumaImage, prompt: rest });
  }
  throw e;
}

Prevention

Never send masks to provider-agnostic image pipelines targeting Luma.
Design edit features prompt-first so they degrade gracefully across providers.
Add a pre-flight capability check when a provider switch can occur at runtime.
Keep a provider-feature matrix in tests to catch mask usage early.

When it happens

Trigger: Calling generateImage with a luma image model and passing a mask (e.g. images array item with mask, or edit options carrying a mask) alongside the source image.

Common situations: Migrating code from OpenAI's DALL·E image edit (which requires a mask) to Luma; building a provider-agnostic pipeline that always includes masks for 'erase object' style edits.

Related errors

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