invoke-ai/InvokeAI · error · ValueError

'{ip_adapter_ckpt_path}' has an unrecognized IP-Adapter mode

Error message

'{ip_adapter_ckpt_path}' has an unrecognized IP-Adapter model architecture.

What it means

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.

Source

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

        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

1. Inspect the image_proj keys in the checkpoint (print(state_dict['image_proj'].keys())) and compare with a known-good IP-Adapter file.
2. 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).
3. Upgrade InvokeAI to a version supporting newer adapter architectures.
4. Write a custom adapter class keyed to the observed layout if you control the checkpoint.

Example fix

// before
# image_proj keys: ['proj_model.net.0.weight'] -> unrecognized
ckpt = '/models/ip_adapter_faceid_plusv2.bin'
// after
# image_proj keys: ['proj.0.weight', ...] -> IPAdapterFull
ckpt = '/models/ip-adapter-full_sd15.bin'

import torch
sd = torch.load(ckpt_path, map_location='cpu')['image_proj']
known = any('proj.0.weight' in k or k.startswith(('proj.', 'perceiver_resampler')) for k in sd)
if not known:
    raise ValueError(f'Unrecognized image_proj keys: {list(sd.keys())[:5]}')

def has_recognized_image_proj(sd) -> bool:
    ip = sd.get('image_proj', {})
    return 'proj.0.weight' in ip or any(k.startswith('proj.') for k in ip)

try:
    model = build_ip_adapter(ckpt_path, device, dtype)
except ValueError as e:
    if 'unrecognized IP-Adapter model architecture' in str(e):
        logger.warning('Falling back: %s is not a supported IP-Adapter', ckpt_path)
        model = None
    else:
        raise

When it happens

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

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

Related errors

• Encountered unexpected IP Adapter state dict key: '{key}'.
• Unsupported IP-Adapter Plus cross-attention dimension: {cros
• Mistral encoder returned only {num_layers} hidden layer(s),
• Unsupported IP-Adapter type: {type(self.ip_adapter)}
• Unsupported IP-Adapter image type: {type(ip_adapter_field.im

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