invoke-ai/InvokeAI · error · Exception

Unsupported IP-Adapter Plus cross-attention dimension: {cros

Error message

Unsupported IP-Adapter Plus cross-attention dimension: {cross_attention_dim}.

What it means

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.

Source

Thrown at invokeai/backend/ip_adapter/ip_adapter.py:254

def build_ip_adapter(
    ip_adapter_ckpt_path: pathlib.Path, device: torch.device, dtype: torch.dtype = torch.float16
) -> Union[IPAdapter, IPAdapterPlus, IPAdapterPlusXL, IPAdapterPlus]:
    state_dict = load_ip_adapter_tensors(ip_adapter_ckpt_path, device.type)

    # IPAdapter (with ImageProjModel)
    if "proj.weight" in state_dict["image_proj"]:
        return IPAdapter(state_dict, device=device, dtype=dtype)

    # IPAdaterPlus or IPAdapterPlusXL (with Resampler)
    elif "proj_in.weight" in state_dict["image_proj"]:
        cross_attention_dim = state_dict["ip_adapter"]["1.to_k_ip.weight"].shape[-1]
        if cross_attention_dim == 768:
            return IPAdapterPlus(state_dict, device=device, dtype=dtype)  # SD1 IP-Adapter Plus
        elif cross_attention_dim == 2048:
            return IPAdapterPlusXL(state_dict, device=device, dtype=dtype)  # SDXL IP-Adapter Plus
        else:
            raise Exception(f"Unsupported IP-Adapter Plus cross-attention dimension: {cross_attention_dim}.")

    # IPAdapterFull (with MLPProjModel)
    elif "proj.0.weight" in state_dict["image_proj"]:
        return IPAdapterFull(state_dict, device=device, dtype=dtype)

    # Unrecognized IP Adapter Architectures
    else:
        raise ValueError(f"'{ip_adapter_ckpt_path}' has an unrecognized IP-Adapter model architecture.")

View on GitHub (pinned to 0b6a024f2f)

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.

Example fix

// before
ckpt = '/models/ip-adapter-plus_sd21.bin'   # cross_attention_dim == 1280
// after
ckpt = '/models/ip-adapter-plus_sd15.bin'   # cross_attention_dim == 768

Defensive patterns

Strategy: validation

Validate before calling

import torch
sd = torch.load(ckpt_path, map_location='cpu')
dim = sd['ip_adapter']['1.to_k_ip.weight'].shape[-1]
if dim not in (768, 2048):
    raise ValueError(f'IP-Adapter Plus dim {dim} unsupported; need 768 (SD1.5) or 2048 (SDXL)')

Type guard

def is_supported_plus_dim(ckpt_path) -> bool:
    sd = torch.load(ckpt_path, map_location='cpu')
    return sd['ip_adapter']['1.to_k_ip.weight'].shape[-1] in (768, 2048)

Try / catch

try:
    model = build_ip_adapter(ckpt_path, device, dtype)
except Exception as e:
    if 'Unsupported IP-Adapter Plus cross-attention dimension' in str(e):
        model = fallback_sd15_ip_adapter  # or re-raise with guidance
    else:
        raise

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/20c8a9276be627be. Report an issue: GitHub.