invoke-ai/InvokeAI · error · ValueError

{self.class} has the config param `encoder_hid_dim_type`

Error message

{self.__class__} has the config param `encoder_hid_dim_type` set to 'image_proj' which requires the keyword argument `image_embeds` to be passed in  `added_conditions`

What it means

For `encoder_hid_dim_type='ip_image_proj'` (IP-Adapter style), the projection embeds `added_cond_kwargs['image_embeds']` and concatenates the result to `encoder_hidden_states` along the token dimension. Without `image_embeds` there is nothing to project, so forward raises.

Source

Thrown at invokeai/backend/hidiffusion/hidiffusion.py:1147

                # Kadinsky 2.1 - style
                if "image_embeds" not in added_cond_kwargs:
                    raise ValueError(
                        f"{self.__class__} has the config param `encoder_hid_dim_type` set to 'text_image_proj' which requires the keyword argument `image_embeds` to be passed in  `added_conditions`"
                    )

                image_embeds = added_cond_kwargs.get("image_embeds")
                encoder_hidden_states = self.encoder_hid_proj(encoder_hidden_states, image_embeds)
            elif self.encoder_hid_proj is not None and self.config.encoder_hid_dim_type == "image_proj":
                # Kandinsky 2.2 - style
                if "image_embeds" not in added_cond_kwargs:
                    raise ValueError(
                        f"{self.__class__} has the config param `encoder_hid_dim_type` set to 'image_proj' which requires the keyword argument `image_embeds` to be passed in  `added_conditions`"
                    )
                image_embeds = added_cond_kwargs.get("image_embeds")
                encoder_hidden_states = self.encoder_hid_proj(image_embeds)
            elif self.encoder_hid_proj is not None and self.config.encoder_hid_dim_type == "ip_image_proj":
                if "image_embeds" not in added_cond_kwargs:
                    raise ValueError(
                        f"{self.__class__} has the config param `encoder_hid_dim_type` set to 'ip_image_proj' which requires the keyword argument `image_embeds` to be passed in  `added_conditions`"
                    )
                image_embeds = added_cond_kwargs.get("image_embeds")
                image_embeds = self.encoder_hid_proj(image_embeds).to(encoder_hidden_states.dtype)
                encoder_hidden_states = torch.cat([encoder_hidden_states, image_embeds], dim=1)

            # 2. pre-process
            sample = self.conv_in(sample)

            # 2.5 GLIGEN position net
            if cross_attention_kwargs is not None and cross_attention_kwargs.get("gligen", None) is not None:
                cross_attention_kwargs = cross_attention_kwargs.copy()
                gligen_args = cross_attention_kwargs.pop("gligen")
                cross_attention_kwargs["gligen"] = {"objs": self.position_net(**gligen_args)}

            # 3. down
            lora_scale = cross_attention_kwargs.get("scale", 1.0) if cross_attention_kwargs is not None else 1.0
            if USE_PEFT_BACKEND:

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass `added_cond_kwargs={'image_embeds': image_embeds}` where image_embeds come from `pipe.prepare_ip_adapter_image_embeds(...)`
Detach/disable the IP-Adapter (`set_ip_adapter_scale(0)` or unload) if image prompting is not needed
Keep using the pipeline API, which computes and passes the embeds automatically

Example fix

// before
unet(sample, t, encoder_hidden_states=text_emb, added_cond_kwargs={})
// after
image_embeds = pipe.prepare_ip_adapter_image_embeds(ip_adapter_image, None, device, 1, False)[0]
unet(sample, t, encoder_hidden_states=text_emb, added_cond_kwargs={'image_embeds': image_embeds})

Defensive patterns

Strategy: validation

Validate before calling

if getattr(unet.config, 'encoder_hid_dim_type', None) == 'ip_image_proj' and not (added_cond_kwargs and 'image_embeds' in added_cond_kwargs):
    raise ValueError("IP-Adapter UNet requires added_cond_kwargs={'image_embeds': ...}")

Type guard

def has_image_embeds(added_cond_kwargs) -> bool:
    return isinstance(added_cond_kwargs, dict) and 'image_embeds' in added_cond_kwargs

Try / catch

try:
    out = unet(sample, t, emb, added_cond_kwargs=ackw)
except ValueError as e:
    if 'ip_image_proj' in str(e):
        ackw = {'image_embeds': ip_embeds}; out = unet(sample, t, emb, added_cond_kwargs=ackw)
    else: raise

Prevention

After loading an IP-Adapter, always use `prepare_ip_adapter_image_embeds` before direct unet calls
Or pass `ip_adapter_image` to the pipeline instead of calling unet.forward yourself
Unload/scale-to-zero the IP-Adapter when not using image prompting

When it happens

Trigger: Calling forward on a UNet with IP-Adapter encoder projection (`encoder_hid_dim_type='ip_image_proj'`) without `added_cond_kwargs={'image_embeds': ...}`, typically after loading an IP-Adapter into the UNet.

Common situations: Loading an IP-Adapter via `load_ip_adapter` but calling `unet.forward` directly without image embeds; running pipelines that forgot `ip_adapter_image`; custom sampling loops that enable IP-Adapter weights but never compute image embeddings.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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