{"record":{"id":"a1bd72d48fe3f1d6","repo":"invoke-ai/InvokeAI","slug":"encoder-hid-dim-type-encoder-hid-dim-type-must","errorCode":null,"errorMessage":"encoder_hid_dim_type: {encoder_hid_dim_type} must be None, 'text_proj' or 'text_image_proj'.","messagePattern":"encoder_hid_dim_type: (.+?) must be None, 'text_proj' or 'text_image_proj'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/util/hotfixes.py","lineNumber":223,"sourceCode":"            raise ValueError(\n                f\"`encoder_hid_dim` has to be defined when `encoder_hid_dim_type` is set to {encoder_hid_dim_type}.\"\n            )\n\n        if encoder_hid_dim_type == \"text_proj\":\n            self.encoder_hid_proj = nn.Linear(encoder_hid_dim, cross_attention_dim)\n        elif encoder_hid_dim_type == \"text_image_proj\":\n            # image_embed_dim DOESN'T have to be `cross_attention_dim`. To not clutter the __init__ too much\n            # they are set to `cross_attention_dim` here as this is exactly the required dimension ...\n            # for the currently only use\n            # case when `addition_embed_type == \"text_image_proj\"` (Kadinsky 2.1)`\n            self.encoder_hid_proj = TextImageProjection(\n                text_embed_dim=encoder_hid_dim,\n                image_embed_dim=cross_attention_dim,\n                cross_attention_dim=cross_attention_dim,\n            )\n\n        elif encoder_hid_dim_type is not None:\n            raise ValueError(\n                f\"encoder_hid_dim_type: {encoder_hid_dim_type} must be None, 'text_proj' or 'text_image_proj'.\"\n            )\n        else:\n            self.encoder_hid_proj = None\n\n        # class embedding\n        if class_embed_type is None and num_class_embeds is not None:\n            self.class_embedding = nn.Embedding(num_class_embeds, time_embed_dim)\n        elif class_embed_type == \"timestep\":\n            self.class_embedding = TimestepEmbedding(timestep_input_dim, time_embed_dim)\n        elif class_embed_type == \"identity\":\n            self.class_embedding = nn.Identity(time_embed_dim, time_embed_dim)\n        elif class_embed_type == \"projection\":\n            if projection_class_embeddings_input_dim is None:\n                raise ValueError(\n                    \"`class_embed_type`: 'projection' requires `projection_class_embeddings_input_dim` be set\"\n                )\n            # The projection `class_embed_type` is the same as the timestep `class_embed_type` except","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/util/hotfixes.py#L205-L241","documentation":"The model constructor only supports three values for `encoder_hid_dim_type`: None, 'text_proj', and 'text_image_proj'. Any other string falls through all supported branches and hits this ValueError. The library enumerates its supported encoder-projection backends explicitly, so an unsupported/typo'd value cannot be silently ignored.","triggerScenarios":"Passing `encoder_hid_dim_type` with a value such as 'image_proj', 'ip_adapter', 'text', or a misspelling like 'text-proj'/'TextProj' to the model constructor or in a loaded config.json. Also occurs when a config from a newer diffusers release uses an encoder_hid_dim_type variant this vendored class does not implement.","commonSituations":"Typos in hand-written configs; copying an encoder_hid_dim_type from a different architecture (e.g. UNet variants that support more types); running an older vendored hotfix copy of the diffusers class against a newer checkpoint config.","solutions":["Set `encoder_hid_dim_type` to one of: None, 'text_proj', or 'text_image_proj' (check exact spelling/casing).","If you need 'text_image' style projection, use 'text_image_proj' and supply both `encoder_hid_dim` and `cross_attention_dim`.","If the value comes from a checkpoint config for a feature this vendored class lacks, upgrade InvokeAI/diffusers or use the stock diffusers class instead of the hotfix copy.","Print/inspect the offending config value before constructing to catch stray whitespace or case mismatches."],"exampleFix":"// before\nmodel = ControlNetModel2_5(\n    encoder_hid_dim=1024,\n    encoder_hid_dim_type=\"image_proj\",\n)\n// after\nmodel = ControlNetModel2_5(\n    encoder_hid_dim=1024,\n    encoder_hid_dim_type=\"text_image_proj\",\n    cross_attention_dim=1024,\n)","handlingStrategy":"validation","validationCode":"ALLOWED = {None, \"text_proj\", \"text_image_proj\"}\nt = model_config.get(\"encoder_hid_dim_type\")\nif t not in ALLOWED:\n    raise ValueError(f\"encoder_hid_dim_type={t!r} not in {sorted(str(a) for a in ALLOWED)}\")","typeGuard":"from typing import Optional, Literal\ndef is_valid_encoder_hid_dim_type(v: Optional[str]) -> bool:\n    return v in (None, \"text_proj\", \"text_image_proj\")","tryCatchPattern":"try:\n    model = ControlNetModel2_5(**cfg)\nexcept ValueError as e:\n    if \"encoder_hid_dim_type\" in str(e):\n        cfg[\"encoder_hid_dim_type\"] = None\n        model = ControlNetModel2_5(**cfg)\n    else:\n        raise","preventionTips":["Use Literal-typed config schemas or enums so invalid values fail at parse time.","Copy enum values from the source class, never retype from memory (watch 'text_proj' vs 'text-proj').","When loading newer checkpoints into vendored classes, check the class supports that encoder_hid_dim_type first.","Keep configs in version control so accidental edits to enum fields are caught in review."],"tags":["config-validation","valueerror","enum","diffusers"],"backgroundTag":"invalid-model-config","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}