What causes "OUTPAINTING requires either a mask image or a mask prompt. Pass mask= or maskPrompt= in the request." in BerriAI/litellm?

Pass a mask image via the OpenAI-style argument: litellm.image_edit(..., mask=open('mask.png', 'rb'))

BerriAI/litellm · error · ValueError

OUTPAINTING requires either a mask image or a mask prompt…

Error message

OUTPAINTING requires either a mask image or a mask prompt. Pass mask=<file> or maskPrompt=<str> in the request.

What it means

Thrown by LiteLLM's Amazon Nova Canvas image-edit request builder when taskType='OUTPAINTING' is requested but the call carries neither a mask image nor a mask prompt. AWS requires outPaintingParams to contain either maskImage or maskPrompt (a text description of which regions to keep/extend), so LiteLLM fails fast client-side before any HTTP request to Bedrock is made.

Solutions

Pass a mask image via the OpenAI-style argument: litellm.image_edit(..., mask=open('mask.png', 'rb'))
Or pass a mask prompt as an optional param: litellm.image_edit(..., maskPrompt='the person, keep unchanged')
Check key spelling: LiteLLM pops 'mask' (OpenAI arg) and 'maskPrompt' (camelCase optional param); other spellings are ignored
If you did not intend outpainting, omit taskType so routing picks INPAINTING (mask present) or IMAGE_VARIATION

Example fix

# before
resp = litellm.image_edit(
    model="bedrock/amazon.nova-canvas-v1:0",
    image=open("cat.png", "rb"),
    prompt="extend the background",
    taskType="OUTPAINTING",
)

# after
resp = litellm.image_edit(
    model="bedrock/amazon.nova-canvas-v1:0",
    image=open("cat.png", "rb"),
    prompt="extend the background",
    taskType="OUTPAINTING",
    mask=open("mask.png", "rb"),          # or maskPrompt="the cat"
    outPaintingMode="PRECISE",
)

Defensive patterns

Strategy: validation

Validate before calling

def validate_outpainting_call(task_type, mask=None, mask_prompt=None):
    if task_type == "OUTPAINTING" and mask is None and not mask_prompt:
        raise ValueError("OUTPAINTING needs mask= or maskPrompt=")

validate_outpainting_call(kwargs.get("taskType"), kwargs.get("mask"), kwargs.get("maskPrompt"))
resp = litellm.image_edit(model=model, image=img, prompt=prompt, **kwargs)

Type guard

def has_outpainting_mask(kwargs: dict) -> bool:
    """True when OUTPAINTING kwargs carry a usable mask source."""
    if kwargs.get("taskType") != "OUTPAINTING":
        return True
    return kwargs.get("mask") is not None or bool(kwargs.get("maskPrompt"))

Try / catch

try:
    resp = litellm.image_edit(...)
except ValueError as e:
    if "OUTPAINTING requires" in str(e):
        raise UserInputError("Provide mask=<file> or maskPrompt=<str> for outpainting") from e
    raise

Prevention

Centralize Nova Canvas edit kwargs in one builder function that asserts mask/maskPrompt for OUTPAINTING
Integration-test every taskType branch of your edit wrapper with minimal fixtures
Remember the key spellings: 'mask' (OpenAI arg) and 'maskPrompt' (optional param)

When it happens

Trigger: litellm.image_edit(model='bedrock/amazon.nova-canvas-v1:0', image=source, prompt='extend the beach', taskType='OUTPAINTING') with no mask= argument and no maskPrompt key in optional params.

Common situations: Porting OpenAI images/edits code to Nova Canvas and assuming mask is optional; passing the mask prompt under a wrong key name (e.g. 'mask_prompt') so _nova_canvas_task_body sees None; building OUTPAINTING calls iteratively and wiring the mask in later.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/8bc9db9195a86f7b. Report an issue: GitHub.

Appendix: source

Thrown at litellm/llms/bedrock/image_edit/amazon_nova_canvas_image_edit_transformation.py:59

    *,
    image_b64: str,
    mask_b64: str | None,
    text: str,
    negative_text: str | None,
    similarity_strength: float | None,
    task_type: str | None,
    mask_prompt: str | None,
    out_painting_mode: str | None,
) -> dict[str, Any]:
    """Build InvokeModel body task section (without imageGenerationConfig)."""
    if task_type == "BACKGROUND_REMOVAL":
        return {
            "taskType": "BACKGROUND_REMOVAL",
            "backgroundRemovalParams": {"image": image_b64},
        }
    if task_type == "OUTPAINTING":
        if mask_prompt is None and mask_b64 is None:
            raise ValueError(
                "OUTPAINTING requires either a mask image or a mask prompt. "
                "Pass mask=<file> or maskPrompt=<str> in the request."
            )
        out_params: Final[dict[str, Any]] = {
            "image": image_b64,
            "text": text,
        }
        if mask_prompt is not None:
            out_params["maskPrompt"] = mask_prompt
        elif mask_b64 is not None:
            out_params["maskImage"] = mask_b64
        if negative_text is not None:
            out_params["negativeText"] = negative_text
        if out_painting_mode is not None:
            out_params["outPaintingMode"] = out_painting_mode
        return {
            "taskType": "OUTPAINTING",
            "outPaintingParams": out_params,

View on GitHub (pinned to 77b7c6c40c)