{"record":{"id":"20c8a9276be627be","repo":"invoke-ai/InvokeAI","slug":"unsupported-ip-adapter-plus-cross-attention-dimens","errorCode":null,"errorMessage":"Unsupported IP-Adapter Plus cross-attention dimension: {cross_attention_dim}.","messagePattern":"Unsupported IP-Adapter Plus cross-attention dimension: (.+?)\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"invokeai/backend/ip_adapter/ip_adapter.py","lineNumber":254,"sourceCode":"\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\"]:\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":236,"sourceCodeEnd":263,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/ip_adapter/ip_adapter.py#L236-L263","documentation":"For IP-Adapter Plus checkpoints, build_ip_adapter selects the model class by reading the cross-attention dimension from 'ip_adapter.1.to_k_ip.weight'. Only 768 (SD1.5) and 2048 (SDXL) are supported; any other dimension (e.g. 1280 for SD2, 4096 for Flux/SD3) has no corresponding wrapper class and raises this error.","triggerScenarios":"Calling build_ip_adapter with an IP-Adapter Plus checkpoint trained for a base model whose text-encoder cross-attention dim is neither 768 nor 2048 — e.g. an SD2.1 (1280), SD3/Flux, or custom-trained adapter.","commonSituations":"Downloading an IP-Adapter Plus variant built for SD2 or another architecture and loading it into an SD1.5/SDXL pipeline config; mixing adapter files between model families.","solutions":["Use an IP-Adapter checkpoint that matches your base model (SD1.5 -> 768-dim, SDXL -> 2048-dim).","Check the dimension yourself: torch.load the file and inspect state_dict['ip_adapter']['1.to_k_ip.weight'].shape[-1].","If you need SD2/other support, add an elif branch returning an appropriate IPAdapterPlus instance or upgrade InvokeAI.","Consider IPAdapterPlusXL only for genuine SDXL adapters — do not force dimensions."],"exampleFix":"// before\nckpt = '/models/ip-adapter-plus_sd21.bin'   # cross_attention_dim == 1280\n// after\nckpt = '/models/ip-adapter-plus_sd15.bin'   # cross_attention_dim == 768","handlingStrategy":"validation","validationCode":"import torch\nsd = torch.load(ckpt_path, map_location='cpu')\ndim = sd['ip_adapter']['1.to_k_ip.weight'].shape[-1]\nif dim not in (768, 2048):\n    raise ValueError(f'IP-Adapter Plus dim {dim} unsupported; need 768 (SD1.5) or 2048 (SDXL)')","typeGuard":"def is_supported_plus_dim(ckpt_path) -> bool:\n    sd = torch.load(ckpt_path, map_location='cpu')\n    return sd['ip_adapter']['1.to_k_ip.weight'].shape[-1] in (768, 2048)","tryCatchPattern":"try:\n    model = build_ip_adapter(ckpt_path, device, dtype)\nexcept Exception as e:\n    if 'Unsupported IP-Adapter Plus cross-attention dimension' in str(e):\n        model = fallback_sd15_ip_adapter  # or re-raise with guidance\n    else:\n        raise","preventionTips":["Match adapter checkpoint to base model family (SD1.5 vs SDXL)","Check to_k_ip.weight shape before loading","Don't reuse SDXL adapters with SD1.5 pipelines or vice versa","Name checkpoint files with their target base model"],"tags":["ip-adapter","model-architecture","dimension-mismatch"],"backgroundTag":"model-architecture-mismatch","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}