{"record":{"id":"8bc9db9195a86f7b","repo":"BerriAI/litellm","slug":"outpainting-requires-either-a-mask-image-or-a-mask","errorCode":null,"errorMessage":"OUTPAINTING requires either a mask image or a mask prompt. Pass mask=<file> or maskPrompt=<str> in the request.","messagePattern":"OUTPAINTING requires either a mask image or a mask prompt\\. Pass mask=<file> or maskPrompt=<str> in the request\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/bedrock/image_edit/amazon_nova_canvas_image_edit_transformation.py","lineNumber":59,"sourceCode":"    *,\n    image_b64: str,\n    mask_b64: str | None,\n    text: str,\n    negative_text: str | None,\n    similarity_strength: float | None,\n    task_type: str | None,\n    mask_prompt: str | None,\n    out_painting_mode: str | None,\n) -> dict[str, Any]:\n    \"\"\"Build InvokeModel body task section (without imageGenerationConfig).\"\"\"\n    if task_type == \"BACKGROUND_REMOVAL\":\n        return {\n            \"taskType\": \"BACKGROUND_REMOVAL\",\n            \"backgroundRemovalParams\": {\"image\": image_b64},\n        }\n    if task_type == \"OUTPAINTING\":\n        if mask_prompt is None and mask_b64 is None:\n            raise ValueError(\n                \"OUTPAINTING requires either a mask image or a mask prompt. \"\n                \"Pass mask=<file> or maskPrompt=<str> in the request.\"\n            )\n        out_params: Final[dict[str, Any]] = {\n            \"image\": image_b64,\n            \"text\": text,\n        }\n        if mask_prompt is not None:\n            out_params[\"maskPrompt\"] = mask_prompt\n        elif mask_b64 is not None:\n            out_params[\"maskImage\"] = mask_b64\n        if negative_text is not None:\n            out_params[\"negativeText\"] = negative_text\n        if out_painting_mode is not None:\n            out_params[\"outPaintingMode\"] = out_painting_mode\n        return {\n            \"taskType\": \"OUTPAINTING\",\n            \"outPaintingParams\": out_params,","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/llms/bedrock/image_edit/amazon_nova_canvas_image_edit_transformation.py#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nresp = litellm.image_edit(\n    model=\"bedrock/amazon.nova-canvas-v1:0\",\n    image=open(\"cat.png\", \"rb\"),\n    prompt=\"extend the background\",\n    taskType=\"OUTPAINTING\",\n)\n\n# after\nresp = litellm.image_edit(\n    model=\"bedrock/amazon.nova-canvas-v1:0\",\n    image=open(\"cat.png\", \"rb\"),\n    prompt=\"extend the background\",\n    taskType=\"OUTPAINTING\",\n    mask=open(\"mask.png\", \"rb\"),          # or maskPrompt=\"the cat\"\n    outPaintingMode=\"PRECISE\",\n)","handlingStrategy":"validation","validationCode":"def validate_outpainting_call(task_type, mask=None, mask_prompt=None):\n    if task_type == \"OUTPAINTING\" and mask is None and not mask_prompt:\n        raise ValueError(\"OUTPAINTING needs mask= or maskPrompt=\")\n\nvalidate_outpainting_call(kwargs.get(\"taskType\"), kwargs.get(\"mask\"), kwargs.get(\"maskPrompt\"))\nresp = litellm.image_edit(model=model, image=img, prompt=prompt, **kwargs)","typeGuard":"def has_outpainting_mask(kwargs: dict) -> bool:\n    \"\"\"True when OUTPAINTING kwargs carry a usable mask source.\"\"\"\n    if kwargs.get(\"taskType\") != \"OUTPAINTING\":\n        return True\n    return kwargs.get(\"mask\") is not None or bool(kwargs.get(\"maskPrompt\"))","tryCatchPattern":"try:\n    resp = litellm.image_edit(...)\nexcept ValueError as e:\n    if \"OUTPAINTING requires\" in str(e):\n        raise UserInputError(\"Provide mask=<file> or maskPrompt=<str> for outpainting\") from e\n    raise","preventionTips":["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)"],"tags":["bedrock","nova-canvas","image-edit","outpainting","mask","client-side-validation"],"backgroundTag":"missing-required-argument","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}