{"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/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/bedrock/image_edit/amazon_nova_canvas_image_edit_transformation.py#L41-L77","documentation":"For Amazon Nova Canvas image edits with explicit taskType='OUTPAINTING', the task-body builder requires a mask: either a mask image (OpenAI mask= parameter) or a maskPrompt string. If both mask_b64 and mask_prompt are None it raises this ValueError, because Bedrock's outPaintingParams API rejects requests without one of maskPrompt/maskImage.","triggerScenarios":"POST /v1/images/edits with model=nova-canvas*, optional_params taskType='OUTPAINTING', and neither a mask file part nor a maskPrompt in optional_params.","commonSituations":"Porting OpenAI images/edits code (which has no maskPrompt concept) to Nova Canvas with taskType set; forgetting that OUTPAINTING on Nova is stricter than OpenAI's optional mask; typo like mask_prompt passed at top level instead of inside optional params.","solutions":["Add maskPrompt to the request's optional params: pass maskPrompt=\"the area to extend\" (or taskType-appropriate mask description).","Or supply a mask image: include the OpenAI-compatible mask= file part, which LiteLLM base64-encodes to maskImage.","If you don't need outpainting, drop taskType so LiteLLM auto-routes (mask -> INPAINTING, else IMAGE_VARIATION)."],"exampleFix":"# before\nresp = litellm.image_edit(\n    model=\"bedrock/amazon.nova-canvas-v1:0\",\n    prompt=\"extend the scene\",\n    image=image_file,\n    taskType=\"OUTPAINTING\",  # no mask -> ValueError\n)\n# after\nresp = litellm.image_edit(\n    model=\"bedrock/amazon.nova-canvas-v1:0\",\n    prompt=\"extend the scene\",\n    image=image_file,\n    taskType=\"OUTPAINTING\",\n    maskPrompt=\"everything outside the person\",\n)","handlingStrategy":"validation","validationCode":"def validate_outpainting(params: dict, mask_present: bool) -> None:\n    if params.get(\"taskType\") == \"OUTPAINTING\" and not (\n        mask_present or params.get(\"maskPrompt\")\n    ):\n        raise ValueError(\"OUTPAINTING needs mask= file or maskPrompt\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat OUTPAINTING as mask-mandatory: always pair it with mask or maskPrompt.","Centralize taskType-specific param checks in one pre-flight validator before calling litellm.","Omit taskType when unsure; auto-routing avoids most class of mismatch errors."],"tags":["bedrock","nova-canvas","image-edit","outpainting","validation"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}