{"record":{"id":"51f3da138f4b6054","repo":"invoke-ai/InvokeAI","slug":"addition-embed-type-addition-embed-type-must-be","errorCode":null,"errorMessage":"addition_embed_type: {addition_embed_type} must be None, 'text' or 'text_image'.","messagePattern":"addition_embed_type: (.+?) must be None, 'text' or 'text_image'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/util/hotfixes.py","lineNumber":275,"sourceCode":"\n            self.add_embedding = TextTimeEmbedding(\n                text_time_embedding_from_dim, time_embed_dim, num_heads=addition_embed_type_num_heads\n            )\n        elif addition_embed_type == \"text_image\":\n            # text_embed_dim and image_embed_dim DON'T have to be `cross_attention_dim`.\n            # 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\"` (Kadinsky 2.1)`\n            self.add_embedding = TextImageTimeEmbedding(\n                text_embed_dim=cross_attention_dim, image_embed_dim=cross_attention_dim, time_embed_dim=time_embed_dim\n            )\n        elif addition_embed_type == \"text_time\":\n            self.add_time_proj = Timesteps(addition_time_embed_dim, flip_sin_to_cos, freq_shift)\n            self.add_embedding = TimestepEmbedding(projection_class_embeddings_input_dim, time_embed_dim)\n\n        elif addition_embed_type is not None:\n            raise ValueError(f\"addition_embed_type: {addition_embed_type} must be None, 'text' or 'text_image'.\")\n\n        # control net conditioning embedding\n        self.controlnet_cond_embedding = ControlNetConditioningEmbedding(\n            conditioning_embedding_channels=block_out_channels[0],\n            block_out_channels=conditioning_embedding_out_channels,\n            conditioning_channels=conditioning_channels,\n        )\n\n        self.down_blocks = nn.ModuleList([])\n        self.controlnet_down_blocks = nn.ModuleList([])\n\n        if isinstance(only_cross_attention, bool):\n            only_cross_attention = [only_cross_attention] * len(down_block_types)\n\n        if isinstance(attention_head_dim, int):\n            attention_head_dim = (attention_head_dim,) * len(down_block_types)\n\n        if isinstance(num_attention_heads, int):","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/util/hotfixes.py#L257-L293","documentation":"The constructor supports only a fixed set of `addition_embed_type` values (None, 'text', 'text_image', plus the 'text_time' branch shown just above the raise). Any other value reaches this final elif and raises a ValueError listing the acceptable options. This guard ensures unsupported extra-embedding backends (used for SDXL-style additive timestep/text conditioning) are rejected at init rather than failing silently later.","triggerScenarios":"Passing `addition_embed_type` values like 'text_time', 'image', 'ip_adapter', or misspellings when the vendored class's supported set is only None/'text'/'text_image'/'text_time'; or a newer diffusers checkpoint config using 'text_time'/'image_hint' variants that this hotfix copy does not enumerate.","commonSituations":"Loading SDXL/SDXL-Turbo-derived checkpoints into the hotfixed ControlNet class; typos when hand-editing configs; version skew where the checkpoint config has an addition_embed_type added in a later diffusers release than the vendored code supports.","solutions":["Use only supported values: omit `addition_embed_type`, or set it to 'text', 'text_image', or 'text_time' (with the required companion args like addition_time_embed_dim and projection_class_embeddings_input_dim).","For SDXL text-time conditioning, set `addition_embed_type='text_time'`, `addition_time_embed_dim=256`, and `projection_class_embeddings_input_dim` to the model's total conditioning dim.","If the checkpoint genuinely requires an unsupported type, upgrade InvokeAI/diffusers or instantiate the stock diffusers model class instead.","Validate the string (case/whitespace/underscore vs hyphen) before passing it in."],"exampleFix":"// before\nmodel = ControlNetModel2_5(\n    addition_embed_type=\"image\",\n)\n// after\nmodel = ControlNetModel2_5(\n    addition_embed_type=\"text_time\",\n    addition_time_embed_dim=256,\n    projection_class_embeddings_input_dim=2816,\n)","handlingStrategy":"validation","validationCode":"SUPPORTED = {None, \"text\", \"text_image\", \"text_time\"}\na = model_config.get(\"addition_embed_type\")\nif a not in SUPPORTED:\n    raise ValueError(f\"addition_embed_type={a!r} not supported; choose from {SUPPORTED}\")","typeGuard":"from typing import Optional\ndef is_valid_addition_embed_type(v: Optional[str]) -> bool:\n    return v in (None, \"text\", \"text_image\", \"text_time\")","tryCatchPattern":"try:\n    model = ControlNetModel2_5(**cfg)\nexcept ValueError as e:\n    if \"addition_embed_type\" in str(e):\n        cfg[\"addition_embed_type\"] = \"text_time\"  # SDXL-style conditioning\n        cfg.setdefault(\"addition_time_embed_dim\", 256)\n        model = ControlNetModel2_5(**cfg)\n    else:\n        raise","preventionTips":["Restrict addition_embed_type in config loaders to the enumerated set with schema validation (pydantic/Literal).","Check the vendored class's supported set before loading SDXL-era checkpoint configs into it.","Pair addition_embed_type='text_time' with addition_time_embed_dim and projection_class_embeddings_input_dim.","Log unknown config keys/values at load time so enum drift is visible early."],"tags":["config-validation","valueerror","enum","sdxl"],"backgroundTag":"invalid-model-config","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}