{"record":{"id":"d22d1ef47841a3ac","repo":"invoke-ai/InvokeAI","slug":"ip-adapter-ckpt-path-has-an-unrecognized-ip-ad","errorCode":null,"errorMessage":"'{ip_adapter_ckpt_path}' has an unrecognized IP-Adapter model architecture.","messagePattern":"'(.+?)' has an unrecognized IP-Adapter model architecture\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/ip_adapter/ip_adapter.py","lineNumber":262,"sourceCode":"        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\"]:\n        cross_attention_dim = state_dict[\"ip_adapter\"][\"1.to_k_ip.weight\"].shape[-1]\n        if cross_attention_dim == 768:\n            return IPAdapterPlus(state_dict, device=device, dtype=dtype)  # SD1 IP-Adapter Plus\n        elif cross_attention_dim == 2048:\n            return IPAdapterPlusXL(state_dict, device=device, dtype=dtype)  # SDXL IP-Adapter Plus\n        else:\n            raise Exception(f\"Unsupported IP-Adapter Plus cross-attention dimension: {cross_attention_dim}.\")\n\n    # IPAdapterFull (with MLPProjModel)\n    elif \"proj.0.weight\" in state_dict[\"image_proj\"]:\n        return IPAdapterFull(state_dict, device=device, dtype=dtype)\n\n    # Unrecognized IP Adapter Architectures\n    else:\n        raise ValueError(f\"'{ip_adapter_ckpt_path}' has an unrecognized IP-Adapter model architecture.\")\n","sourceCodeStart":244,"sourceCodeEnd":263,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/ip_adapter/ip_adapter.py#L244-L263","documentation":"This is the final fallback in build_ip_adapter: after checking for IP-Adapter Plus and IPAdapterFull ('proj.0.weight') image-projection layouts, the image_proj sub-dict matches no known projection architecture. InvokeAI cannot map the checkpoint to any implemented class and raises ValueError naming the checkpoint path.","triggerScenarios":"Calling build_ip_adapter with a state dict whose image_proj keys are none of the recognized patterns (e.g. missing both 'proj.weight'-style plus keys and 'proj.0.weight'), such as IP-Adapter-FaceID Plus v2, ControlNet-IPAdapter hybrids, or a restructured export.","commonSituations":"Loading community adapters from repos not derived from the standard tencent/H94 IP-Adapter layout; converting checkpoints with tools that rename keys; loading a future adapter format with an older InvokeAI.","solutions":["Inspect the image_proj keys in the checkpoint (print(state_dict['image_proj'].keys())) and compare with a known-good IP-Adapter file.","Use an official IP-Adapter checkpoint whose image_proj contains recognizable keys (image_proj.proj.0.weight for Full, or the Plus-style per-block keys).","Upgrade InvokeAI to a version supporting newer adapter architectures.","Write a custom adapter class keyed to the observed layout if you control the checkpoint."],"exampleFix":"// before\n# image_proj keys: ['proj_model.net.0.weight'] -> unrecognized\nckpt = '/models/ip_adapter_faceid_plusv2.bin'\n// after\n# image_proj keys: ['proj.0.weight', ...] -> IPAdapterFull\nckpt = '/models/ip-adapter-full_sd15.bin'","handlingStrategy":"validation","validationCode":"import torch\nsd = torch.load(ckpt_path, map_location='cpu')['image_proj']\nknown = any('proj.0.weight' in k or k.startswith(('proj.', 'perceiver_resampler')) for k in sd)\nif not known:\n    raise ValueError(f'Unrecognized image_proj keys: {list(sd.keys())[:5]}')","typeGuard":"def has_recognized_image_proj(sd) -> bool:\n    ip = sd.get('image_proj', {})\n    return 'proj.0.weight' in ip or any(k.startswith('proj.') for k in ip)","tryCatchPattern":"try:\n    model = build_ip_adapter(ckpt_path, device, dtype)\nexcept ValueError as e:\n    if 'unrecognized IP-Adapter model architecture' in str(e):\n        logger.warning('Falling back: %s is not a supported IP-Adapter', ckpt_path)\n        model = None\n    else:\n        raise","preventionTips":["Prefer official IP-Adapter / IP-Adapter Plus / FaceID checkpoints with known layouts","Diff the checkpoint's image_proj keys against a known-good file","Keep InvokeAI updated for new adapter architecture support","Document checkpoint provenance (repo, revision) alongside model files"],"tags":["ip-adapter","model-architecture","checkpoint-loading"],"backgroundTag":"unrecognized-checkpoint-format","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}