{"record":{"id":"183654afe0b58dcc","repo":"invoke-ai/InvokeAI","slug":"encountered-unexpected-ip-adapter-state-dict-key","errorCode":null,"errorMessage":"Encountered unexpected IP Adapter state dict key: '{key}'.","messagePattern":"Encountered unexpected IP Adapter state dict key: '(.+?)'\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/ip_adapter/ip_adapter.py","lineNumber":229,"sourceCode":"        \"ip_adapter\": {},\n        \"image_proj\": {},\n        \"adapter_modules\": {},  # added for noobai-mark-ipa\n        \"image_proj_model\": {},  # added for noobai-mark-ipa\n    }\n\n    if ip_adapter_ckpt_path.suffix == \".safetensors\":\n        model = safetensors.torch.load_file(ip_adapter_ckpt_path, device=device)\n        for key in model.keys():\n            if key.startswith(\"ip_adapter.\"):\n                state_dict[\"ip_adapter\"][key.replace(\"ip_adapter.\", \"\")] = model[key]\n            elif key.startswith(\"image_proj_model.\"):\n                state_dict[\"image_proj_model\"][key.replace(\"image_proj_model.\", \"\")] = model[key]\n            elif key.startswith(\"image_proj.\"):\n                state_dict[\"image_proj\"][key.replace(\"image_proj.\", \"\")] = model[key]\n            elif key.startswith(\"adapter_modules.\"):\n                state_dict[\"adapter_modules\"][key.replace(\"adapter_modules.\", \"\")] = model[key]\n            else:\n                raise RuntimeError(f\"Encountered unexpected IP Adapter state dict key: '{key}'.\")\n    else:\n        ip_adapter_diffusers_checkpoint_path = ip_adapter_ckpt_path / \"ip_adapter.bin\"\n        state_dict = torch.load(ip_adapter_diffusers_checkpoint_path, map_location=\"cpu\")\n\n    return state_dict\n\n\ndef build_ip_adapter(\n    ip_adapter_ckpt_path: pathlib.Path, device: torch.device, dtype: torch.dtype = torch.float16\n) -> Union[IPAdapter, IPAdapterPlus, IPAdapterPlusXL, IPAdapterPlus]:\n    state_dict = load_ip_adapter_tensors(ip_adapter_ckpt_path, device.type)\n\n    # IPAdapter (with ImageProjModel)\n    if \"proj.weight\" in state_dict[\"image_proj\"]:\n        return IPAdapter(state_dict, device=device, dtype=dtype)\n\n    # IPAdaterPlus or IPAdapterPlusXL (with Resampler)\n    elif \"proj_in.weight\" in state_dict[\"image_proj\"]:","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/ip_adapter/ip_adapter.py#L211-L247","documentation":"When loading an IP-Adapter checkpoint, InvokeAI buckets every tensor key into one of three sub-dicts (image_proj_model, image_proj, adapter_modules) based on key prefixes. If a key in the loaded state dict starts with none of those prefixes, the checkpoint does not match any known IP-Adapter layout, so load_ip_adapter_tensors refuses to silently drop data and raises this RuntimeError.","triggerScenarios":"Calling build_ip_adapter (via _load_model) with an IP-Adapter checkpoint file whose state dict contains keys outside the recognized prefixes — e.g. a corrupted/custom/resaved checkpoint, a different adapter family (IP-Adapter-FaceID, ControlNet-adjacent weights), or a file with extra keys like 'lora' or metadata tensors.","commonSituations":"Users point InvokeAI at an IP-Adapter .bin/.safetensors downloaded from a non-standard repo, hand-edited or converted checkpoints, or newer adapter formats released after this InvokeAI version was published.","solutions":["Verify the checkpoint is an official IP-Adapter file (h94/IP-Adapter) and re-download it","Open the file with torch.load / safetensors and inspect its keys to confirm they start with image_proj_model., image_proj., or adapter_modules.","Upgrade InvokeAI — newer versions recognize more IP-Adapter checkpoint formats.","If the file contains unrelated extra keys, strip them (re-save only the recognized tensors) rather than patching the loader."],"exampleFix":"// before\nip_adapter = Path('/models/ip_adapter/custom_faceid.bin')  # unknown key layout\n// after\nip_adapter = Path('/models/ip_adapter/ip-adapter-plus_sd15.bin')  # official layout","handlingStrategy":"validation","validationCode":"import torch\nsd = torch.load(path, map_location='cpu')\nvalid = ('image_proj_model.', 'image_proj.', 'adapter_modules.')\nbad = [k for k in sd.keys() if not k.startswith(valid)]\nif bad:\n    raise ValueError(f'Unrecognized IP-Adapter keys: {bad[:5]}')","typeGuard":"def is_ip_adapter_state_dict(sd) -> bool:\n    prefixes = ('image_proj_model.', 'image_proj.', 'adapter_modules.')\n    return all(k.startswith(prefixes) for k in sd.keys())","tryCatchPattern":"try:\n    ip_adapter = build_ip_adapter(ckpt_path, device, dtype)\nexcept RuntimeError as e:\n    if 'unexpected IP Adapter state dict key' in str(e):\n        logger.error('Checkpoint is not a supported IP-Adapter layout: %s', ckpt_path)\n        ip_adapter = None\n    else:\n        raise","preventionTips":["Only use checkpoints from official IP-Adapter repos (h94/IP-Adapter)","Inspect state dict keys with torch.load before loading into the pipeline","Pin and update InvokeAI versions when adopting new adapter formats","Keep a checksum/manifest of known-good adapter files"],"tags":["ip-adapter","checkpoint-loading","model-conversion"],"backgroundTag":"unrecognized-checkpoint-format","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}