invoke-ai/InvokeAI · error · ValueError

FLUX IP-Adapter only supports a single image prompt (receive

Error message

FLUX IP-Adapter only supports a single image prompt (received {len(ipa_image_fields)}).

What it means

The FLUX (XLabs) IP-Adapter implementation consumes exactly one image prompt per adapter. If the normalized image field list contains zero or multiple ImageFields, this ValueError is raised before embedding computation.

Source

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

        device: torch.device,
    ) -> tuple[list[torch.Tensor], list[torch.Tensor]]:
        """Run the IPAdapter CLIPVisionModel, returning image prompt embeddings."""
        clip_image_processor = CLIPImageProcessor()

        pos_image_prompt_clip_embeds: list[torch.Tensor] = []
        neg_image_prompt_clip_embeds: list[torch.Tensor] = []
        for ip_adapter_field in ip_adapter_fields:
            # `ip_adapter_field.image` could be a list or a single ImageField. Normalize to a list here.
            ipa_image_fields: list[ImageField]
            if isinstance(ip_adapter_field.image, ImageField):
                ipa_image_fields = [ip_adapter_field.image]
            elif isinstance(ip_adapter_field.image, list):
                ipa_image_fields = ip_adapter_field.image
            else:
                raise ValueError(f"Unsupported IP-Adapter image type: {type(ip_adapter_field.image)}")

            if len(ipa_image_fields) != 1:
                raise ValueError(
                    f"FLUX IP-Adapter only supports a single image prompt (received {len(ipa_image_fields)})."
                )

            ipa_images = [context.images.get_pil(image.image_name, mode="RGB") for image in ipa_image_fields]

            pos_images: list[npt.NDArray[np.uint8]] = []
            neg_images: list[npt.NDArray[np.uint8]] = []
            for ipa_image in ipa_images:
                assert ipa_image.mode == "RGB"
                pos_image = np.array(ipa_image)
                # We use a black image as the negative image prompt for parity with
                # https://github.com/XLabs-AI/x-flux-comfyui/blob/45c834727dd2141aebc505ae4b01f193a8414e38/nodes.py#L592-L593
                # An alternative scheme would be to apply zeros_like() after calling the clip_image_processor.
                neg_image = np.zeros_like(pos_image)
                pos_images.append(pos_image)
                neg_images.append(neg_image)

            with context.models.load(ip_adapter_field.image_encoder_model) as image_encoder_model:

View on GitHub (pinned to 0b6a024f2f)

Solutions

Connect exactly one image to the IP-Adapter invocation.
For multiple image prompts, create multiple IP-Adapter invocations (one image each) and pass a list of IPAdapterFields.
If migrating from SDXL workflows, remove the extra images rather than reusing the same graph with FLUX.

Example fix

// before: one IP-Adapter with image list [img1, img2]
// after: two IP-Adapter invocations, each with a single image, both feeding flux_denoise.ip_adapter

Defensive patterns

Strategy: validation

Validate before calling

imgs = ip_adapter_field.image if isinstance(ip_adapter_field.image, list) else [ip_adapter_field.image]
if len(imgs) != 1:
    raise ValueError(f"FLUX IP-Adapter needs exactly 1 image, got {len(imgs)}")

Type guard

def is_single_image(image) -> bool:
    if isinstance(image, ImageField):
        return True
    return isinstance(image, list) and len(image) == 1 and isinstance(image[0], ImageField)

Try / catch

try:
    result = flux_denoise.invoke(context)
except ValueError as e:
    if "only supports a single image prompt" in str(e):
        log.error("Provide exactly one image per FLUX IP-Adapter node")
    else:
        raise

Prevention

Use one IP-Adapter node per image prompt on FLUX.
Do not connect collection outputs (batch image lists) to a FLUX IP-Adapter image input.
Audit SDXL workflows before porting them to FLUX.

When it happens

Trigger: Passing a list of 0 or >=2 images (or a list-valued image connection) to a FLUX IP-Adapter used with flux_denoise; batch image collections wired into a single IP-Adapter node.

Common situations: Reusing an SDXL/SD1.5 IP-Adapter workflow (which supports multiple images) with the FLUX denoise node; accidentally connecting an image collection output instead of a single image.

Related errors

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