{"record":{"id":"58391fde92c3d73f","repo":"invoke-ai/InvokeAI","slug":"ip-adapter-masks-are-not-yet-supported-in-flux","errorCode":null,"errorMessage":"IP-Adapter masks are not yet supported in Flux.","messagePattern":"IP-Adapter masks are not yet supported in Flux\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/flux_denoise.py","lineNumber":979,"sourceCode":"    def _prep_ip_adapter_extensions(\n        self,\n        ip_adapter_fields: list[IPAdapterField],\n        pos_image_prompt_clip_embeds: list[torch.Tensor],\n        neg_image_prompt_clip_embeds: list[torch.Tensor],\n        context: InvocationContext,\n        exit_stack: ExitStack,\n        dtype: torch.dtype,\n    ) -> tuple[list[XLabsIPAdapterExtension], list[XLabsIPAdapterExtension]]:\n        pos_ip_adapter_extensions: list[XLabsIPAdapterExtension] = []\n        neg_ip_adapter_extensions: list[XLabsIPAdapterExtension] = []\n        for ip_adapter_field, pos_image_prompt_clip_embed, neg_image_prompt_clip_embed in zip(\n            ip_adapter_fields, pos_image_prompt_clip_embeds, neg_image_prompt_clip_embeds, strict=True\n        ):\n            ip_adapter_model = exit_stack.enter_context(context.models.load(ip_adapter_field.ip_adapter_model))\n            assert isinstance(ip_adapter_model, XlabsIpAdapterFlux)\n            ip_adapter_model = ip_adapter_model.to(dtype=dtype)\n            if ip_adapter_field.mask is not None:\n                raise ValueError(\"IP-Adapter masks are not yet supported in Flux.\")\n            ip_adapter_extension = XLabsIPAdapterExtension(\n                model=ip_adapter_model,\n                image_prompt_clip_embed=pos_image_prompt_clip_embed,\n                weight=ip_adapter_field.weight,\n                begin_step_percent=ip_adapter_field.begin_step_percent,\n                end_step_percent=ip_adapter_field.end_step_percent,\n            )\n            ip_adapter_extension.run_image_proj(dtype=dtype)\n            pos_ip_adapter_extensions.append(ip_adapter_extension)\n\n            ip_adapter_extension = XLabsIPAdapterExtension(\n                model=ip_adapter_model,\n                image_prompt_clip_embed=neg_image_prompt_clip_embed,\n                weight=ip_adapter_field.weight,\n                begin_step_percent=ip_adapter_field.begin_step_percent,\n                end_step_percent=ip_adapter_field.end_step_percent,\n            )\n            ip_adapter_extension.run_image_proj(dtype=dtype)","sourceCodeStart":961,"sourceCodeEnd":997,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/flux_denoise.py#L961-L997","documentation":"FLUX IP-Adapter support (XLabs) does not implement spatial masking. If an IPAdapterField carries a non-None mask, _prep_ip_adapter_extensions raises this ValueError before the denoise loop starts.","triggerScenarios":"An IP-Adapter invocation configured with a mask input (as commonly done for SD1.5/SDXL regional prompting) is connected to a FLUX denoise invocation.","commonSituations":"Porting an SDXL workflow that uses IP-Adapter masks for regional style control to FLUX; enabling the mask input by habit without realizing FLUX lacks support.","solutions":["Disconnect/clear the mask input on the IP-Adapter invocation when targeting FLUX.","Achieve regional effects by using multiple single-image IP-Adapter invocations with weights/begin-end step percentages instead of masks.","Track InvokeAI releases for FLUX IP-Adapter mask support before re-adding the mask."],"exampleFix":"// before: IPAdapter(mask=mask_field) -> flux_denoise\n// after: IPAdapter(mask=None) -> flux_denoise (mask input left unconnected)","handlingStrategy":"validation","validationCode":"if ip_adapter_field.mask is not None:\n    raise ValueError(\"Clear the IP-Adapter mask before using it with FLUX denoise\")","typeGuard":"def is_flux_compatible_ipa(field: IPAdapterField) -> bool:\n    return field.mask is None","tryCatchPattern":"try:\n    result = flux_denoise.invoke(context)\nexcept ValueError as e:\n    if \"masks are not yet supported in Flux\" in str(e):\n        log.warning(\"Dropping mask for FLUX IP-Adapter\")\n        ip_adapter_field = replace(ip_adapter_field, mask=None)\n    else:\n        raise","preventionTips":["Leave the mask input unconnected on IP-Adapter nodes used with FLUX.","Use weights and begin/end step percentages for regional influence instead of masks.","Check release notes for FLUX mask support before enabling masks."],"tags":["python","valueerror","flux","ip-adapter","unsupported-feature"],"backgroundTag":"feature-not-supported","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}