invoke-ai/InvokeAI · error · ValueError

`encoder_hid_dim` has to be defined when `encoder_hid_dim_ty

Error message

`encoder_hid_dim` has to be defined when `encoder_hid_dim_type` is set to {encoder_hid_dim_type}.

What it means

The model's __init__ (a diffusers-compatible UNet/ControlNet constructor in hotfixes.py) allows `encoder_hid_dim_type` to be set (explicitly or defaulted from `encoder_hid_dim`), but requires the hidden dimension `encoder_hid_dim` to accompany it. If `encoder_hid_dim` is None while `encoder_hid_dim_type` is not None, the encoder projection layer (e.g. nn.Linear) cannot be constructed, so the library raises this ValueError immediately. It is a config-consistency guard, not a runtime failure.

Source

Thrown at invokeai/backend/util/hotfixes.py:205

        )

        # time
        time_embed_dim = block_out_channels[0] * 4
        self.time_proj = Timesteps(block_out_channels[0], flip_sin_to_cos, freq_shift)
        timestep_input_dim = block_out_channels[0]
        self.time_embedding = TimestepEmbedding(
            timestep_input_dim,
            time_embed_dim,
            act_fn=act_fn,
        )

        if encoder_hid_dim_type is None and encoder_hid_dim is not None:
            encoder_hid_dim_type = "text_proj"
            self.register_to_config(encoder_hid_dim_type=encoder_hid_dim_type)
            logger.info("encoder_hid_dim_type defaults to 'text_proj' as `encoder_hid_dim` is defined.")

        if encoder_hid_dim is None and encoder_hid_dim_type is not None:
            raise ValueError(
                f"`encoder_hid_dim` has to be defined when `encoder_hid_dim_type` is set to {encoder_hid_dim_type}."
            )

        if encoder_hid_dim_type == "text_proj":
            self.encoder_hid_proj = nn.Linear(encoder_hid_dim, cross_attention_dim)
        elif encoder_hid_dim_type == "text_image_proj":
            # image_embed_dim DOESN'T have to be `cross_attention_dim`. To not clutter the __init__ too much
            # they are set to `cross_attention_dim` here as this is exactly the required dimension ...
            # for the currently only use
            # case when `addition_embed_type == "text_image_proj"` (Kadinsky 2.1)`
            self.encoder_hid_proj = TextImageProjection(
                text_embed_dim=encoder_hid_dim,
                image_embed_dim=cross_attention_dim,
                cross_attention_dim=cross_attention_dim,
            )

        elif encoder_hid_dim_type is not None:
            raise ValueError(

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Add `encoder_hid_dim=<int>` (matching your text encoder hidden size, e.g. 768 or 1024) to the constructor/config alongside `encoder_hid_dim_type`.
2. If you do not need an encoder hid projection, remove `encoder_hid_dim_type` (set it to None) so the default path (`encoder_hid_proj = None`) is taken.
3. Load the model via its official `from_pretrained`/`from_config` with the original config.json instead of hand-constructing kwargs.
4. If migrating from an older diffusers checkpoint, diff the config against the reference model class defaults and restore the dropped `encoder_hid_dim` key.

Example fix

// before
model = ControlNetModel2_5(
    encoder_hid_dim_type="text_proj",
    cross_attention_dim=1024,
)
// after
model = ControlNetModel2_5(
    encoder_hid_dim=1024,
    encoder_hid_dim_type="text_proj",
    cross_attention_dim=1024,
)

cfg = model_config  # dict of constructor kwargs
if cfg.get("encoder_hid_dim_type") is not None and cfg.get("encoder_hid_dim") is None:
    raise ValueError("encoder_hid_dim must be set whenever encoder_hid_dim_type is set")

def encoder_hid_ok(cfg: dict) -> bool:
    return cfg.get("encoder_hid_dim_type") is None or isinstance(cfg.get("encoder_hid_dim"), int)

try:
    model = ControlNetModel2_5(**cfg)
except ValueError as e:
    if "encoder_hid_dim" in str(e):
        cfg["encoder_hid_dim"] = text_encoder_hidden_size
        model = ControlNetModel2_5(**cfg)
    else:
        raise

When it happens

Trigger: Calling the model constructor (or from_config/from_pretrained with a config dict) with `encoder_hid_dim_type='text_proj'` or `'text_image_proj'` while `encoder_hid_dim` is omitted/None. Also happens when a hand-edited config.json sets encoder_hid_dim_type but drops encoder_hid_dim, or when loading a checkpoint whose config was partially migrated between diffusers versions.

Common situations: Hand-writing UNet2DConditionModel/ControlNet kwargs for IP-Adapter or custom text-encoder setups; copying config from a different model class; diffusers version upgrades that renamed/relocated encoder_hid_dim defaults; JSON config edits where one of the paired keys was deleted.

Related errors

• encoder_hid_dim_type: {encoder_hid_dim_type} must be None, '
• `class_embed_type`: 'projection' requires `projection_class_
• User not found or inactive
• Missing authentication credentials
• Invalid or expired authentication token

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