invoke-ai/InvokeAI · error · ValueError

IP-Adapter masks are not yet supported in Flux.

Error message

IP-Adapter masks are not yet supported in Flux.

What it means

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.

Source

Thrown at invokeai/app/invocations/flux_denoise.py:979

    def _prep_ip_adapter_extensions(
        self,
        ip_adapter_fields: list[IPAdapterField],
        pos_image_prompt_clip_embeds: list[torch.Tensor],
        neg_image_prompt_clip_embeds: list[torch.Tensor],
        context: InvocationContext,
        exit_stack: ExitStack,
        dtype: torch.dtype,
    ) -> tuple[list[XLabsIPAdapterExtension], list[XLabsIPAdapterExtension]]:
        pos_ip_adapter_extensions: list[XLabsIPAdapterExtension] = []
        neg_ip_adapter_extensions: list[XLabsIPAdapterExtension] = []
        for ip_adapter_field, pos_image_prompt_clip_embed, neg_image_prompt_clip_embed in zip(
            ip_adapter_fields, pos_image_prompt_clip_embeds, neg_image_prompt_clip_embeds, strict=True
        ):
            ip_adapter_model = exit_stack.enter_context(context.models.load(ip_adapter_field.ip_adapter_model))
            assert isinstance(ip_adapter_model, XlabsIpAdapterFlux)
            ip_adapter_model = ip_adapter_model.to(dtype=dtype)
            if ip_adapter_field.mask is not None:
                raise ValueError("IP-Adapter masks are not yet supported in Flux.")
            ip_adapter_extension = XLabsIPAdapterExtension(
                model=ip_adapter_model,
                image_prompt_clip_embed=pos_image_prompt_clip_embed,
                weight=ip_adapter_field.weight,
                begin_step_percent=ip_adapter_field.begin_step_percent,
                end_step_percent=ip_adapter_field.end_step_percent,
            )
            ip_adapter_extension.run_image_proj(dtype=dtype)
            pos_ip_adapter_extensions.append(ip_adapter_extension)

            ip_adapter_extension = XLabsIPAdapterExtension(
                model=ip_adapter_model,
                image_prompt_clip_embed=neg_image_prompt_clip_embed,
                weight=ip_adapter_field.weight,
                begin_step_percent=ip_adapter_field.begin_step_percent,
                end_step_percent=ip_adapter_field.end_step_percent,
            )
            ip_adapter_extension.run_image_proj(dtype=dtype)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Disconnect/clear the mask input on the IP-Adapter invocation when targeting FLUX.
2. Achieve regional effects by using multiple single-image IP-Adapter invocations with weights/begin-end step percentages instead of masks.
3. Track InvokeAI releases for FLUX IP-Adapter mask support before re-adding the mask.

Example fix

// before: IPAdapter(mask=mask_field) -> flux_denoise
// after: IPAdapter(mask=None) -> flux_denoise (mask input left unconnected)

if ip_adapter_field.mask is not None:
    raise ValueError("Clear the IP-Adapter mask before using it with FLUX denoise")

def is_flux_compatible_ipa(field: IPAdapterField) -> bool:
    return field.mask is None

try:
    result = flux_denoise.invoke(context)
except ValueError as e:
    if "masks are not yet supported in Flux" in str(e):
        log.warning("Dropping mask for FLUX IP-Adapter")
        ip_adapter_field = replace(ip_adapter_field, mask=None)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unsupported IP-Adapter type: {type(self.ip_adapter)}
• Unsupported IP-Adapter image type: {type(ip_adapter_field.im
• FLUX IP-Adapter only supports a single image prompt (receive
• Unknown lora: {lora_key}!
• LoRA model is in unsupported FLUX format

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/58391fde92c3d73f. Report an issue: GitHub.